erectl uploads
List, inspect, cancel, and delete upload sessions from the terminal. One verb per action. Bulk operations are not supported.
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.
erectl upload ./my-model "My Model" --metadata model.json
Related limits (initiating uploads):
- Default chunk size: Erebine defaults to
100 MiBper chunk. This diverges from OpenAI's64 MBdefault; 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:
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.
# 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.
# 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.
# 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 ascancelled. - 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.
# 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
# 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
# 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
# List sessions currently uploading
erectl uploads --status uploading
# Check progress of a specific session
erectl uploads upl_abc123
Export Session List as JSON
erectl uploads -o json | jq '.data[] | {id, status, filename, progressPercent}'