Skip to main content

Upload from a connected site

After connecting your agent, run these commands from the connected folder. The CLI uses that site’s connection for every file.
A successful upload returns a hosted URL and an upload ID with --json. Put the URL in your post or component. Connected uploads support JPEG, PNG, WebP, AVIF, GIF, TTF, OTF, WOFF, WOFF2, MP4, and WebM within your site’s upload limit. The library includes assets uploaded through the web editor and other agents. Pass --cursor with the returned nextCursor for another page. If an upload’s response is interrupted, use its upload ID to check whether the file was saved before retrying.

Upload with an account login

Outside a connected site folder, sign in to upload images or fonts:
Use this command when you need a URL to put in your source, including custom fonts and images for GitHub publishing. lettercamp deploy can upload referenced local images automatically without changing your local files. upload uses its remembered upload destination, or the site remembered by deploy when no upload destination is saved. Use --site my-blog to choose explicitly. This selection does not change your deployment destination or let deploy replace that site’s source. Images support JPEG, PNG, WebP, AVIF, and GIF. Fonts support TTF, OTF, WOFF, and WOFF2. Uploads follow your site’s file-size limit. JSON output includes image dimensions or a font’s url, name, and variable weight range when available. Use the returned font object as design.typography.headingFont or design.typography.bodyFont in settings.json. Image uploads trigger the same background optimization as uploads through the web editor. The command returns the original URL as soon as the upload succeeds; it does not wait for optimization. Keep that URL in your content. Lettercamp uses ready optimized versions when you publish and falls back to the original when needed. GIFs, animated images, and AVIF uploads keep their originals. Font uploads do not run image optimization.

Upload with an agent using an account login

An agent building or editing your publication can use lettercamp upload for the images and fonts needed for your requested changes. Once you have signed in with lettercamp login, the command reuses that saved session. You do not need to upload each file manually or sign in again for every upload. From the publication folder, the agent can check the session and upload to your existing site:
Replace my-blog with the destination site’s slug. --site makes the destination explicit and remembers it for uploads after a successful upload. Later uploads can omit it. The command also uses a site previously remembered by deploy, or selects the only accessible site when no site is remembered. With multiple available sites and no selection, it exits with instructions to pass --site; it does not prompt. Uploads need an existing accessible Cloud site. If none exists, create a site in Cloud or through the deployment workflow first. If the session has expired or been revoked, run npx lettercamp login again and complete browser authorization. The agent should:
  1. Upload the required files with --json and read the returned URLs. Reuse URLs already saved in the publication instead of uploading unchanged files again.
  2. Write those URLs into Markdown, MDX, custom components, or settings.json. Uploading alone does not edit your source or publish the site. Preserve image dimensions where the component supports them, and provide descriptive alt text.
  3. For a batch with failures, keep the successful URLs and fix or retry only the failed files. Each result includes its file and either asset metadata or an error; the command exits unsuccessfully if any file fails.
  4. Run npx lettercamp check --json after updating the source and fix any problems before publishing. check never uploads assets.
You can continue editing and publish while optimization runs. If a build uses the original because variants are not ready, publish again to include variants that finish later. Do not construct variant URLs yourself. For files that should keep local paths, deploy uploads public/ and prepares supported referenced images outside it. Use upload when you want a hosted URL available in the source immediately, including for GitHub publishing or an image otherwise linked from an external host.

Options and output

With multiple files, plain output contains a filename and URL separated by a tab. If a file fails, the CLI reports it and continues with the remaining files. The command exits unsuccessfully if any upload fails.