xeroctl uploads
Inspect, cancel, and delete model upload sessions. Use this command to manage in-progress or completed upload sessions -- not to start new uploads.
Overview
The xeroctl uploads command manages existing upload sessions
created by the xeroctl upload command (which initiates model
uploads). Use uploads to check progress, cancel stuck sessions,
or clean up completed records.
Note: To start a new model upload, use xeroctl upload <path> <name>. The uploads command only manages sessions that already exist.
The command follows the unified 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.
List Upload Sessions
Omit all IDs and action flags to list upload sessions. The table shows ID, Filename, Size, Status, Progress, and Created time.
# List all sessions
xeroctl uploads
# Filter by status
xeroctl uploads --status uploading
xeroctl uploads --status pending
xeroctl uploads --status completed
xeroctl uploads --status failed
# 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.
Get Upload Session
Provide an upload session ID to display its full details.
# 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
Cancel a running or pending upload session. The session transitions to a
cancelled status and no further chunks will be accepted. Use --dry-run
to preview without making changes.
# 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
Delete an upload session record. A confirmation prompt is shown unless
--force is supplied. Use --dry-run to preview.
# 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
Deleting a session that is still in progress does not cancel the underlying transfer. Cancel the session first if needed.
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. |
processing |
All chunks received; the platform is assembling and validating the upload. |
completed |
Upload finished successfully and the model is available for use. |
failed |
The upload encountered an unrecoverable error. |
Note: The --status filter on xeroctl uploads passes the value directly to the API. Accepted values are those shown in the table above. The API may return a validation error if an unrecognised value is supplied.
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, processing, completed, failed. |
Examples
Find and Cancel a Stuck Upload
# 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
# List completed sessions
xeroctl uploads --status completed
# Delete one without prompt
xeroctl uploads upl_abc123 --delete --force
Watch Active Uploads
# List sessions currently uploading
xeroctl uploads --status uploading
# Check progress of a specific session
xeroctl uploads upl_abc123
Export Session List as JSON
xeroctl uploads -o json | jq '.data[] | {id, status, filename, progressPercent}'
