cast files

Manage files in Castari’s managed storage. Upload, list, and manage files that can be attached to agents.

Command Overview

Command	Description
`cast files list`	List files in storage
`cast files upload`	Upload a file
`cast files get`	Get file details
`cast files delete`	Delete a file
`cast files download`	Download a file
`cast files usage`	Show storage usage

cast files list

List files in your managed storage.

Usage

cast files list [options]

Options

Option	Description
`--limit <n>`	Maximum files to return (default: 50)
`--offset <n>`	Number of files to skip (default: 0)
`--scope <scope>`	Filter by scope: `user`, `agent`, `session`
`--tags <tags>`	Filter by tags (comma-separated)
`--search <query>`	Search in filename and description

Example

cast files list

Output

File ID                  Filename                       Size         Scope      Created
file_abc123              training-data.csv              2.4 MB       user       Jan 15, 2024
file_def456              config.json                    1.2 KB       user       Jan 14, 2024
file_ghi789              reference.txt                  45.6 KB      user       Jan 13, 2024

ℹ Showing 3 of 3 files

Filter by Tags

cast files list --tags dataset,csv

Search Files

cast files list --search training

cast files upload

Upload a file to managed storage.

Usage

cast files upload <path> [options]

Arguments

Argument	Description
`path`	Local file path to upload

Options

Option	Description
`--description <desc>`	File description
`--tags <tags>`	Comma-separated tags

Example

cast files upload data.csv --description "Training data" --tags dataset,ml

Output

✓ Uploaded data.csv

  File ID    file_abc123
  Size       2.4 MB

  → Attach to agent: cast agents files add <agent-slug> file_abc123

Files larger than 10MB automatically use presigned uploads for better performance.

cast files get

Get detailed information about a file.

Usage

cast files get <file_id>

Example

cast files get file_abc123

Output

  File ID       file_abc123
  Filename      data.csv
  Size          2.4 MB
  Content Type  text/csv
  Scope         user
  Status        confirmed
  Description   Training data
  Tags          dataset, ml
  SHA256        a1b2c3d4e5f6...
  Created       Jan 15, 2024 10:30 AM
  Updated       Jan 15, 2024 10:30 AM

cast files delete

Delete a file from storage.

Usage

cast files delete <file_id> [options]

Options

Option	Description
`-f, --force`	Skip confirmation prompt

Example

cast files delete file_abc123

Output

Are you sure you want to delete file 'file_abc123'? [y/N] y
✓ File 'file_abc123' deleted

Deleting a file will also detach it from any agents it was attached to.

cast files download

Download a file from storage.

Usage

cast files download <file_id> [options]

Options

Option	Description
`--output <path>`	Output file path (default: original filename)

Example

cast files download file_abc123 --output ./local-data.csv

Output

✓ Downloaded to ./local-data.csv
ℹ Size: 2.4 MB

cast files usage

Show your storage usage and quota.

Usage

cast files usage

Example

cast files usage

Output

  Total Files    12
  Total Size     45.2 MB
  Quota Used     45.2%
  Quota Limit    100 MB

  ████████████████████░░░░░░░░░░░░░░░░░░░░ 45.2%

Agent Files Commands

Manage files attached to specific agents.

cast agents files list

List files attached to an agent.

cast agents files list <slug>

Example

cast agents files list my-agent

Output

File ID                  Filename                 Mount Path                    Size         Mode
file_abc123              data.csv                 /files/agent/data.csv         2.4 MB       ro
file_def456              config.json              /files/agent/config.json      1.2 KB       ro

ℹ 2 files attached (2.4 MB total)

cast agents files add

Attach a file to an agent.

cast agents files add <slug> <file_id> [options]

Options

Option	Description
`--mount-path <path>`	Custom mount path (default: `/files/agent/<filename>`)
`--writable`	Make file writable (default: read-only)

Example

cast agents files add my-agent file_abc123

Output

✓ File attached to agent 'my-agent'

  File ID      file_abc123
  Filename     data.csv
  Mount Path   /files/agent/data.csv
  Mode         read-only

  → File will be available at /files/agent/data.csv in the sandbox

cast agents files remove

Detach a file from an agent.

cast agents files remove <slug> <file_id> [options]

Options

Option	Description
`-f, --force`	Skip confirmation prompt

Example

cast agents files remove my-agent file_abc123

Output

Detach file 'file_abc123' from agent 'my-agent'? [y/N] y
✓ File 'file_abc123' detached from agent 'my-agent'

Workflow Example

Complete workflow for using files with an agent:

# 1. Upload a file
cast files upload training-data.csv --description "ML training data"
# → file_abc123

# 2. Attach to agent
cast agents files add my-ml-agent file_abc123

# 3. Verify attachment
cast agents files list my-ml-agent

# 4. Deploy and run agent
cast deploy my-ml-agent
cast invoke my-ml-agent "Process the training data"

# 5. Clean up when done
cast agents files remove my-ml-agent file_abc123

​cast files

​Command Overview

​cast files list

​Usage

​Options

​Example

​Output

​Filter by Tags

​Search Files

​cast files upload

​Usage

​Arguments

​Options

​Example

​Output

​cast files get

​Usage

​Example

​Output

​cast files delete

​Usage

​Options

​Example

​Output

​cast files download

​Usage

​Options

​Example

​Output

​cast files usage

​Usage

​Example

​Output

​Agent Files Commands

​cast agents files list

​Example

​Output

​cast agents files add

​Options

​Example

​Output

​cast agents files remove

​Options

​Example

​Output

​Workflow Example

​See Also

cast files

Command Overview

cast files list

Usage

Options

Example

Output

Filter by Tags

Search Files

cast files upload

Usage

Arguments

Options

Example

Output

cast files get

Usage

Example

Output

cast files delete

Usage

Options

Example

Output

cast files download

Usage

Options

Example

Output

cast files usage

Usage

Example

Output

Agent Files Commands

cast agents files list

Example

Output

cast agents files add

Options

Example

Output

cast agents files remove

Options

Example

Output

Workflow Example

See Also