> ## Documentation Index
> Fetch the complete documentation index at: https://www.lettercamp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload media

> Upload images, fonts, and videos, browse a connected site’s media library, and retrieve hosted URLs.

## Upload from a connected site

After [connecting your agent](https://www.lettercamp.com/docs/cli/connect.md), run these commands from the connected
folder. The CLI uses that site's connection for every file.

```bash theme={null}
npx lettercamp upload cover.png brand.woff2 clip.mp4 --json
npx lettercamp assets list --type image --query cover
npx lettercamp assets list --source cli --limit 20
npx lettercamp assets list --upload-id "<upload ID>"
```

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:

```bash theme={null}
npx lettercamp login
npx lettercamp upload cover.png brand.woff2
npx lettercamp upload brand.ttf --json
```

Use this command when you need a URL to put in your source, including custom fonts
and images for GitHub publishing. [`lettercamp deploy`](https://www.lettercamp.com/docs/publishing/deploy#local-images-and-cloud-assets)
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](https://www.lettercamp.com/docs/components/image.md#automatic-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:

```bash theme={null}
npx lettercamp whoami --json
npx lettercamp upload cover.png portrait.jpg --site my-blog --json
```

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](https://www.lettercamp.com/docs/publishing/deploy.md) 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`](https://www.lettercamp.com/docs/cli/check) 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`](https://www.lettercamp.com/docs/publishing/deploy#local-images-and-cloud-assets)
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

| Option | Purpose |
| - | - |
| `--site <slug>` | Select and remember the destination for account uploads. In a connected folder, the slug must match the paired site. |
| `--json` | Print URL and image dimensions or font settings. Multiple files return an array. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.