vetta file

Upload inputs for a session and download published outputs.

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

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

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

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

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

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.

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:

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

​

publish & rm

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:

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.