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

# vetta file

> Upload inputs for a session and download published outputs.

Manage [files](/docs/capabilities/files) — inputs you hand to a session, and outputs an agent publishes with `publish_file`. Files are org-scoped objects with a `fil_` id.

<Note>
  The group is **`file`**, singular — matching `agent`, `session`, and `webhook`. The delete verb is **`rm`**. Unknown commands are a hard error, so `vetta files delete` exits `2` rather than deleting anything.
</Note>

## Commands

| Command                    | Description                                       |
| -------------------------- | ------------------------------------------------- |
| `vetta file upload`        | Upload a local file; returns a `fil_` id.         |
| `vetta file list`          | List files in the org.                            |
| `vetta file show <id>`     | Show a file's metadata.                           |
| `vetta file download <id>` | Print a file's contents to stdout.                |
| `vetta file publish <id>`  | Promote a file to the `published` scope.          |
| `vetta file rm <id>`       | Delete a file.                                    |
| `vetta file update <id>`   | Set a file's title, description or tags.          |
| `vetta file import <url>`  | Fetch a public URL into the library, server-side. |

## upload

```bash theme={"system"}
vetta file upload --file ./contracts/order-4821.pdf
```

| Flag            | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `--file`        | Path to the local file (required).                               |
| `--name`        | Override the stored name. Defaults to the basename.              |
| `--scope`       | File scope, e.g. `published`.                                    |
| `--session`     | Attach the upload to a session.                                  |
| `--title`       | A human title for the library.                                   |
| `--description` | A longer, searchable description.                                |
| `--tag`         | A label; repeat the flag or comma-separate (`--tag launch,web`). |

## list

```bash theme={"system"}
vetta file list --limit 2
```

```json theme={"system"}
{
  "data": [
    {
      "id": "fil_h361txkmkapcpavpwfetebat9x",
      "object": "file",
      "name": "report.md",
      "content_type": "text/markdown",
      "size_bytes": 24,
      "scope": "published",
      "session_id": null,
      "sha256": "88cd3bcda30fee16ca4d9d7a7d43aa06123b0ca56409159e4b3364f229a9ae27",
      "created_at": "2026-08-22T23:56:39.813Z"
    }
  ],
  "has_more": true,
  "next_cursor": "fil_m7fjsd5hg5mt09sgaaya5m0hcb"
}
```

| Flag                  | Description                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--scope`             | Filter by scope.                                                                                                                   |
| `--session`           | Only files belonging to one session — this is how you list what a run produced.                                                    |
| `--kind`              | `image`, `video`, `audio`, `document` or `other` — derived from the content type.                                                  |
| `--source`            | Provenance: `upload`, `url_import`, `image_generation`, `video_generation`, `video_clipping`, `screenshot` or `speech_generation`. |
| `--tag`               | Only files carrying this tag.                                                                                                      |
| `--search`            | Case-insensitive match on the title, name or description.                                                                          |
| `--limit` / `--after` | Pagination.                                                                                                                        |

```bash theme={"system"}
vetta file list --kind image --tag launch --search hero
```

A `--kind` or `--source` outside its list exits `2` before any request is sent. `sha256` is the content hash, so you can verify a download without a second request.

## update

```bash theme={"system"}
vetta file update fil_... --title "Launch hero (final)" --tag launch --tag approved
vetta file update fil_... --description ""     # an empty value clears the field
```

| Flag            | Description                                 |
| --------------- | ------------------------------------------- |
| `--title`       | Set the title; `""` clears it.              |
| `--description` | Set the description; `""` clears it.        |
| `--tag`         | Replace the tags; repeat or comma-separate. |

Only the flags you pass change. The bytes, name and scope never do.

## import

```bash theme={"system"}
vetta file import https://cdn.example.com/hero.png --title "Launch hero" --tag launch
```

The API fetches the URL itself — nothing is read from your machine — and stores a `published` file with `source.type: "url_import"`. Only public `http(s)` URLs are accepted, up to 25 MiB. The CLI sends an `Idempotency-Key` so a retried command returns the same file.

| Flag            | Description                       |
| --------------- | --------------------------------- |
| `--title`       | A human title.                    |
| `--description` | A longer, searchable description. |
| `--tag`         | Labels; repeat or comma-separate. |

## download

`download` writes the contents to **stdout**; there is no `--out` flag. Redirect it:

```bash theme={"system"}
vetta file download fil_h361txkmkapcpavpwfetebat9x > ./out/report.md
```

## publish & rm

```bash theme={"system"}
vetta file publish fil_...     # promote to the published scope
vetta file rm fil_...          # delete
```

`show`, `download`, `publish`, and `rm` take the file id as a positional argument and accept no flags.

## What a run produced

There is no `vetta session files` command. List a session's files by filtering this group:

```bash theme={"system"}
vetta file list --session ses_xq5542edbac2dssv3gm6atdcr8
```

<Warning>
  Deleting a session removes files that were never published from its sandbox. Publish anything you need to keep first — see [Files](/docs/capabilities/files).
</Warning>