> ## 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.                            |

## 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.                     |

## 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. |
| `--limit` / `--after` | Pagination.                                                                     |

`sha256` is the content hash, so you can verify a download without a second request.

## 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>