> ## 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](https://vetta.sh/docs/capabilities/files.md) — 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.

## 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>` | Write the file's bytes to stdout, unchanged. |
| `vetta file publish <id>` | Promote a file to the `published` scope. |
| `vetta file rm <id>…` | Delete a file, or up to 100 in one request. |
| `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. |
| `vetta file move <id>…` | Put files in a folder, or rename, merge or empty a whole folder. |
| `vetta file folders` | List every folder. |

## 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`). |
| `--folder` | Put the file in this folder. |

## 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. Several, comma-separated: `--kind image,video`. |
| `--exclude-kind` | Leave these kinds out, comma-separated. |
| `--agent` | Only files an agent's sessions made (`agt_…`). |
| `--character` | Only what was rendered as one [character](https://vetta.sh/docs/cli/character.md) (`chr_…`): its stills and the clips made from them. |
| `--ids` | Exactly these files, comma-separated `fil_` ids. |
| `--order` | `desc` (newest first, the default) or `asc`. |
| `--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. |
| `--folder` | Only files in this folder. Case does not matter. |
| `--limit` / `--after` | Pagination. |

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

Every picture and clip one agent made, oldest first: `vetta file list --kind image,video --agent agt_… --order asc`.

A `--kind`, `--exclude-kind`, `--source` or `--order` 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. |
| `--folder` | Move the file to this folder; `""` takes it out of its folder. |

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. |
| `--folder` | Put the file in this folder. |

## Folders

A folder is a name on a file. A file is in one folder or none, and folders do not nest. A name is 1–64 characters with no `/`. If a folder with the same name in another case exists, the file takes that folder's spelling. A file an agent writes with no folder lands in the folder of the last file its session filed.

```bash theme={"system"}
vetta file move fil_... fil_... --folder Launch        # put files in a folder
vetta file move --from Launch --folder "Launch 2026"   # rename; a name in use merges the two
vetta file move --from Launch --folder ""              # empty the folder; the files stay
vetta file folders                                     # every folder, newest first
```

| Flag | Description |
| - | - |
| `--folder` | The folder to move to (required); `""` takes the files out of any folder. |
| `--from` | Move every file in this folder, instead of naming ids. |

Name up to 100 file ids, or `--from`, not both. `move` answers `{ object: "file_move", folder, file_ids }`. `folders` takes no flags and answers each folder's `name`, `file_count`, `newest_at`, `cover_file_ids` and `agent_id`. No file is ever deleted by a folder change.

## 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
vetta file rm fil_... fil_...  # delete several in one request (POST /v1/files/delete), up to 100
```

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

## 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](https://vetta.sh/docs/capabilities/files.md).


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