// Tools

xeroctl uploads

List, inspect, cancel, and delete upload sessions from the terminal. One verb per action. Bulk operations are not supported.

surface // CLI wrapper over /v1/uploads auth // inherits xeroctl config key chord // g i jumps to index, g e jumps to errors

Overview

xeroctl uploads is the management surface for existing chunked upload sessions: list, inspect, cancel, delete. New sessions are created by xeroctl upload, not here.

To start a new upload: xeroctl upload <path> <name>. This page does not initiate transfers.

Related limits (initiating uploads):

  • Default chunk size: Xerotier defaults to 100 MiB per chunk. This diverges from OpenAI's 64 MB default; clients written against the OpenAI SDK may need to set chunk size explicitly when targeting Xerotier.
  • Maximum upload size: Not a fixed value. The router resolves the maximum allowed size per request via resolveMaxUploadSize, which honours the caller's tier and project quota. There is no flat 8 GB ceiling; consult your tier configuration for the effective limit.

The command follows the unified pattern:

Pattern
xeroctl uploads # List upload sessions xeroctl uploads <id> # Show session details xeroctl uploads <id> --cancel # Cancel a running session xeroctl uploads <id> --delete # Delete a session record

--cancel and --delete are mutually exclusive. Both require an upload session ID.

Back to xeroctl CLI overview.

Command Index

Every xeroctl uploads verb in scan order. Click a row to jump.

Verb Invocation Purpose
LIST xeroctl uploads List sessions. Filterable by --status, capped by --limit.
GET xeroctl uploads <id> Show one session: status, progress, chunk counts, expiry.
CANCEL xeroctl uploads <id> --cancel Stop an in-flight session. No further chunks accepted.
DELETE xeroctl uploads <id> --delete Delete a session record. Currently aliases cancel server-side.

--cancel and --delete are mutually exclusive. Both require a session ID. Add --dry-run to preview without mutating state; add -o json to any verb for machine-readable output.

List Upload Sessions

Omit all IDs and action flags to list upload sessions. The table shows ID, Filename, Size, Status, Progress, and Created time.

bash
# List all sessions xeroctl uploads # Filter by status xeroctl uploads --status uploading xeroctl uploads --status pending xeroctl uploads --status completed xeroctl uploads --status cancelled xeroctl uploads --status expired # Limit the number of results xeroctl uploads --limit 10 # Combine filter and limit xeroctl uploads --status uploading --limit 5 # JSON output xeroctl uploads -o json

When more results exist a hint is printed at the end of the table. Use --limit to adjust the page size.

--status values are not validated. The flag is forwarded as-is to GET /v1/uploads?status=<value>. Unknown values do not error; they yield an empty list. Use only the values listed under Status Values: pending, uploading, completed, cancelled, expired.

Get Upload Session

Provide an upload session ID to display its full details.

bash
# Human-readable key-value output xeroctl uploads upl_abc123 # JSON output xeroctl uploads upl_abc123 -o json

The detail view includes: ID, Status, Filename, Size, Type, Chunk Size, Total Chunks, Uploaded Chunks, Progress, Created, and Expires.

Progress is shown as a percentage string when available. When not directly available, it is computed from the uploaded and total chunk counts.

Cancel Upload

Stop a running or pending session. The session moves to cancelled and refuses further chunks. Use --dry-run to preview.

bash
# Cancel an upload session xeroctl uploads upl_abc123 --cancel # Preview without cancelling xeroctl uploads upl_abc123 --cancel --dry-run

After cancellation the CLI prints the session ID and updated status.

Delete Upload Session

Drop a session record. The CLI prompts for confirmation unless --force is set. Use --dry-run to preview.

bash
# Delete with confirmation prompt xeroctl uploads upl_abc123 --delete # Skip confirmation xeroctl uploads upl_abc123 --delete --force # Preview without deleting xeroctl uploads upl_abc123 --delete --dry-run

Important: --delete currently maps to the DELETE /v1/uploads/{id} endpoint, which the router implements as an alias for cancel. In effect, --delete on an in-progress session does cancel the underlying transfer rather than only removing a record. Treat --delete and --cancel as having the same server-side effect today.

Status Values

Upload sessions move through the following statuses during their lifecycle. Use --status when listing to filter to a specific state.

Status Description
pending Session created; no chunks have been uploaded yet.
uploading Chunks are actively being received by the platform.
completed Upload finished successfully and the model is available for use.
cancelled Session was cancelled (via --cancel or --delete); no further chunks are accepted.
expired Session passed its expiry deadline before completion and was retired by the platform.

Options Reference

Full reference for all flags and options accepted by xeroctl uploads.

Action Flags (mutually exclusive)

Flag Requires Session ID Description
--cancel Yes Cancel an active upload session.
--delete Yes Delete an upload session record. Prompts for confirmation unless --force is set.

Modifier and List Options

Option Description
--force Skip the confirmation prompt when deleting a session.
--limit <n> Maximum number of results when listing (1-100).
--status <value> Filter list results by status. Accepted values: pending, uploading, completed, cancelled, expired. The value is passed through to the API without server-side validation; unknown values yield an empty list.

Failure Modes

What you see when a command does not succeed, and where to look next. The CLI exits non-zero on every failure; the table below maps the surface signal to its cause.

Surface Cause Remediation
not found on get / cancel / delete Session ID does not exist for this project, or already cleaned up at expiry. Run xeroctl uploads to list current sessions. Use Status Values to scope by state.
Empty list with --status set Either no sessions match or --status value is misspelled (not validated). Re-run without --status to confirm sessions exist. Then check the value against Status Values.
Conflict / already terminal Cancel or delete issued against a session already in completed, cancelled, or expired. Read the session first: xeroctl uploads <id>. Terminal states do not need a follow-up action.
Auth failure (401 / 403) The configured API key is missing, revoked, or not scoped to this project. Verify with xeroctl config; rotate via xeroctl keys if needed.
Network or 5xx Transport failure or transient server error. Retry. Sessions are durable; cancel and delete are idempotent at the API layer.
Both --cancel and --delete set Mutually exclusive flags; CLI rejects before issuing a request. Pick one. --delete currently aliases cancel server-side; see the warning under Delete Upload Session.

Examples

Find and Cancel a Stuck Upload

bash
# List sessions stuck in uploading state xeroctl uploads --status uploading # Inspect a specific session xeroctl uploads upl_abc123 # Cancel it xeroctl uploads upl_abc123 --cancel

Clean Up Completed Sessions

bash
# List completed sessions xeroctl uploads --status completed # Delete one without prompt xeroctl uploads upl_abc123 --delete --force

Watch Active Uploads

bash
# List sessions currently uploading xeroctl uploads --status uploading # Check progress of a specific session xeroctl uploads upl_abc123

Export Session List as JSON

bash
xeroctl uploads -o json | jq '.data[] | {id, status, filename, progressPercent}'

xeroctl CLI

Overview of all xeroctl commands, installation, and configuration.

Model Upload API

REST API reference for the chunked model upload protocol.

xeroctl models

Manage model metadata, versions, and catalog sharing.