vetta file

Manage files — inputs you hand to a session, and outputs an agent publishes with publish_file. Files are org-scoped objects with a fil_ id.

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

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

vetta file list --limit 2

{
  "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.

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

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

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:

vetta file download fil_h361txkmkapcpavpwfetebat9x > ./out/report.md

publish & rm

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:

vetta file list --session ses_xq5542edbac2dssv3gm6atdcr8

Deleting a session removes files that were never published from its sandbox. Publish anything you need to keep first — see Files.

Getting started

Building & running

Organization

Identity

Commands

upload

list

update

import

download

publish & rm

What a run produced

​Commands

​upload

​list

​update

​import

​download

​publish & rm

​What a run produced

Commands

upload

list

update

import

download

publish & rm

What a run produced