docs
// Tools

erectl 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 erectl config key chord // g i jumps to index, g e jumps to errors

Overview

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

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

Metadata With an Upload

erectl upload <path> <name> --metadata <file.json> applies a metadata file once the new model has validated. The file is checked before the transfer starts, so a typo costs nothing. --metadata implies --wait: the file is applied when the model status is active or validation_failed, because validation reads the model's config.json. A file that sets an engine setting needs an API key with the management scope; without it the command refuses before the transfer starts. If the server refuses the file, the upload stands: the command exits non-zero and prints the model id with the erectl models update <id> --metadata <file.json> command that applies it again.

bash
erectl upload ./my-model "My Model" --metadata model.json

Related limits (initiating uploads):

  • Default chunk size: Erebine 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 Erebine.
  • 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
erectl uploads # List upload sessions erectl uploads <id> # Show session details erectl uploads <id> --cancel # Cancel a running session erectl uploads <id> --delete # Remove a session

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

Back to erectl CLI overview.

Command Index

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

Verb Invocation Purpose
LIST erectl uploads List sessions. Filterable by --status, capped by --limit.
GET erectl uploads <id> Show one session: status, progress, chunk counts, expiry.
CANCEL erectl uploads <id> --cancel Stop an in-flight session. No further chunks accepted.
DELETE erectl uploads <id> --delete Remove a session. Cancels one in progress; a finished one keeps its model.

--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 erectl uploads # Filter by status erectl uploads --status uploading erectl uploads --status pending erectl uploads --status completed erectl uploads --status cancelled erectl uploads --status expired # Limit the number of results erectl uploads --limit 10 # Combine filter and limit erectl uploads --status uploading --limit 5 # JSON output erectl 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, failed, cancelled, expired.

Get Upload Session

Provide an upload session ID to display its full details.

bash
# Human-readable key-value output erectl uploads upl_abc123 # JSON output erectl 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, refuses further chunks, and the partial model and what it uploaded are deleted. A completed upload cannot be cancelled; the command fails and the model stays. Use --dry-run to preview.

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

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

Delete Upload Session

Remove a session. What happens depends on its state:

  • In progress: the upload is cancelled, as with --cancel. The session stays in the list as cancelled.
  • Completed: only the session record is removed. The model made from it stays; delete it with erectl models <id> --delete.

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

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

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.
failed Completion refused the upload, for example an invalid model layout or config, or an archive that cannot be extracted. The model shows error with the reason. Upload again to retry.
cancelled Session was cancelled (via --cancel or --delete) before it completed; 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 erectl uploads.

Action Flags (mutually exclusive)

Flag Requires Session ID Description
--cancel Yes Cancel an active upload session.
--delete Yes Remove an upload session: cancels one in progress, keeps a finished one's model. 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, failed, 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 erectl 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 on cancel Cancel issued against a session that already completed. Its model stays. Delete the model with erectl models <id> --delete, or remove the session with --delete.
Auth failure (401 / 403) The configured API key is missing, revoked, or not scoped to this project. Verify with erectl config; rotate via erectl keys if needed.
Network or 5xx Transport failure or transient server error. Retry. Sessions are durable and a repeated cancel is harmless; a repeated delete of a finished session that was already removed answers not found.
Both --cancel and --delete set Mutually exclusive flags; CLI rejects before issuing a request. Pick one. --delete cancels a session in progress and removes a finished one; see Delete Upload Session.

Examples

Find and Cancel a Stuck Upload

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

Clean Up Completed Sessions

bash
# List completed sessions erectl uploads --status completed # Remove one without prompt; the model it made stays erectl uploads upl_abc123 --delete --force

Watch Active Uploads

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

Export Session List as JSON

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