Object Storage (S3)¶

The verda object-storage commands provide AWS-CLI-style access to Verda's S3-compatible object storage (the oss alias is shorter: verda oss ls). They use a separate credential set (keys prefixed verda_s3_) so object-storage access is independent of your main API credentials while still sharing the profile system.

Every command works two ways: non-interactively with positional URIs and flags (for scripts, pipes, and AI agents), and interactively with a TUI when you omit the target on a terminal.

Command reference¶

Configure credentials¶

First create an access key in the Verda dashboard: log in → select your project → Project management → Credentials → Object Storage Access Keys.

Run the interactive wizard. The endpoint and region come pre-filled with defaults (https://objects.fin-03.verda.storage, us-east-1), so you normally just pick a profile and paste the access key and secret:

verda object-storage configure

Non-interactive (endpoint defaults if omitted; pass --endpoint for another region):

verda object-storage configure \
  --access-key AKIA... \
  --secret-key ...

Show the active configuration (no secrets are printed):

verda object-storage show
verda object-storage show --profile staging

S3 credentials are stored in the same credentials file as your API credentials (~/.verda/credentials), using verda_s3_-prefixed keys.

List buckets and objects¶

verda object-storage ls                              # list all buckets
verda object-storage ls s3://my-bucket               # top-level keys + prefixes (delimiter /)
verda object-storage ls s3://my-bucket --recursive   # every key under the bucket
verda object-storage ls s3://my-bucket --human-readable --summarize

On a terminal, running verda object-storage ls with no argument opens an interactive folder browser — drill into prefixes, run per-object actions, or multi-select objects to download.

Copy files¶

# upload
verda object-storage cp ./local-file s3://my-bucket/key.txt

# download
verda object-storage cp s3://my-bucket/key.txt ./local-file

# server-side copy (S3 → S3, no data traverses the client)
verda object-storage cp s3://src-bucket/key s3://dst-bucket/key

# recursive directory upload
verda object-storage cp ./dir s3://my-bucket/prefix/ --recursive

# with include/exclude filters (match against relative path; * does not cross /)
verda object-storage cp ./dir s3://my-bucket/prefix/ --recursive \
  --include '*.go' --exclude '*_test.go'

# override content-type (otherwise inferred from extension)
verda object-storage cp ./file s3://my-bucket/key --content-type 'application/json'

# preview what would happen
verda object-storage cp ./dir s3://my-bucket/prefix/ --recursive --dryrun

# tune throughput for large transfers
verda object-storage cp ./big.bin s3://my-bucket/big.bin --concurrency 16 --part-size 32MiB

To upload without typing an s3:// URI, run verda object-storage cp <file> with no destination on a terminal — a wizard picks the destination bucket and folder for you:

Resumable large transfers¶

Single-file uploads and single-object downloads larger than the part size are multipart, parallel (5 concurrent parts by default), and resumable. If a transfer is interrupted (network drop, Ctrl+C, crash), re-run the exact same command and it continues — only the missing parts are sent or fetched:

# upload; if it breaks, run the SAME command again to resume
verda object-storage cp ./model.safetensors s3://my-bucket/models/model.safetensors

# download; re-run to resume (a partial <dest>.part is kept until it completes)
verda object-storage cp s3://my-bucket/models/model.safetensors ./model.safetensors

# force a fresh transfer, ignoring any saved progress
verda object-storage cp s3://my-bucket/models/model.safetensors ./model.safetensors --no-resume

A few details worth knowing:

• Resume reuses the same part size that the interrupted run used. Passing a different --part-size (or changing the file) is detected and the transfer restarts cleanly. Part sizes accept binary forms (MiB, GiB); the loose MB/M forms are also treated as binary (1MB = 1048576 bytes).
• Resume state lives locally: uploads under ~/.verda/s3-uploads/, downloads under ~/.verda/s3-downloads/ (plus a <dest>.part file). The key is a hash of the source path + destination, so resume requires re-running with the same source and destination.

• Incomplete uploads stage parts on the server that cost storage until completed or aborted. Use verda object-storage ls-uploads to list them (and pick one to resume) and verda object-storage abort-uploads to clean them up.

  

• No silent overwrites: if a local file of the same name already exists, an interactive download is saved as name-2.ext, name-3.ext, … A genuine resume of the same object keeps its original name so its .part is continued.

• Recursive (--recursive), sync, and mv transfers are not yet resumable per-file.

Move files¶

mv has the same flag surface as cp; the source is removed on success.

verda object-storage mv ./tmpfile s3://my-bucket/final-name
verda object-storage mv s3://my-bucket/old-key s3://my-bucket/new-key

On a terminal, verda object-storage mv with no arguments (or a single s3:// source) opens an S3 → S3 move/rename wizard. Local ↔ S3 moves always require both explicit arguments.

Sync directories¶

# local → S3
verda object-storage sync ./local-dir s3://my-bucket/prefix/

# S3 → local
verda object-storage sync s3://my-bucket/prefix/ ./local-dir

# remove destination files that don't exist in source (AWS-convention --delete)
verda object-storage sync ./a s3://bucket/ --delete

# treat any mtime difference as "changed" (not just newer-source)
verda object-storage sync ./a s3://bucket/ --exact-timestamps --dryrun

By default, sync copies a file when the source size differs or the source is newer. --exact-timestamps instead copies on any mtime difference.

Remove objects¶

verda object-storage rm s3://bucket/key
verda object-storage rm s3://bucket/prefix/ --recursive
verda object-storage rm s3://bucket/prefix/ --recursive --include '*.log' --yes
verda object-storage rm s3://bucket/prefix/ --recursive --dryrun

Buckets¶

verda object-storage mb s3://new-bucket-name

verda object-storage rb s3://old-bucket              # only works if empty
verda object-storage rb s3://old-bucket --force      # empty the bucket first, then remove

rb prompts for confirmation unless --yes. --force implies a recursive delete of the bucket contents, so be sure before using it.

Presigned URLs¶

Generate a time-limited GET URL for an object:

verda object-storage presign s3://bucket/key                    # default 1h
verda object-storage presign s3://bucket/key --expires-in 15m
verda object-storage presign s3://bucket/key --expires-in 24h

The URL is printed to stdout (pipe-friendly) and the expiration hint goes to stderr, so it's safe to pipe:

verda object-storage presign s3://bucket/key --expires-in 30m | pbcopy

Multiple profiles¶

Profiles work across both API and S3 credentials. Create a second profile via:

verda object-storage configure --profile staging

configure and show take a local --profile flag. The other commands (ls, cp, rm, …) have no local --profile flag — select a profile with the global --auth.profile staging, the VERDA_PROFILE=staging environment variable, or persist it with verda auth use staging.

Output formats¶

All commands honour the global output flags:

• --output table (default)
• --output json / --output yaml — a single structured payload at the end
• --agent — disables interactive prompts, implies JSON, and requires --yes for destructive operations
• --debug — dumps SDK request/response metadata to stderr

Per-file progress lines (uploaded, downloaded, copied, moved, deleted) are only emitted when the format is table. Structured output produces exactly one payload so it stays parseable.

Interactive vs non-interactive¶

The interactive TUI triggers only when stdout is a terminal, you're not in --agent mode, and the output format is the default table. Otherwise an omitted target returns the command help (or a structured error in --agent).

Esc steps back (ascends a folder or returns to the previous wizard step); Ctrl+C exits immediately.

Environment variables¶