xeroctl files
List, inspect, upload, download, and delete files used for batch processing and other purposes.
Overview
The xeroctl files command manages files stored in the platform's
Files API. Files are used primarily as batch input
and output containers, but can also be uploaded for general purposes such as
assistant context.
The command follows the unified pattern:
xeroctl files # List files
xeroctl files <file_id> # Show file details
xeroctl files <file_id> --delete # Delete a file
xeroctl files <file_id> --download <path> # Download file content
xeroctl files --upload <path> --purpose <p> # Upload a file
Action flags (--delete, --download,
--upload) are mutually exclusive. Only one may be specified per
invocation.
Back to xeroctl CLI overview.
List Files
Omit all IDs and action flags to list files in the current project. The table shows ID, Filename, Purpose, Size, Status, and Created time.
# List all files (default limit: 20)
xeroctl files
# Filter by purpose
xeroctl files --purpose batch
# Increase result limit
xeroctl files --limit 50
# Combine filters
xeroctl files --purpose assistants --limit 100
# JSON output
xeroctl files -o json
When more results exist beyond the current page, a hint is printed. Use
--limit to retrieve more items in a single request.
Get File
Show the metadata for a specific file by its ID.
# Human-readable key-value output
xeroctl files file-abc123
# JSON output
xeroctl files file-abc123 -o json
The detail view shows: ID, Filename, Purpose, Status, Size, and Created time.
Upload a File
Upload a local file to the platform. A purpose must be specified for the file
to be routed correctly. If --purpose is omitted, it defaults to
"assistants".
# Upload a batch input file
xeroctl files --upload requests.jsonl --purpose batch
# Upload with default purpose (assistants)
xeroctl files --upload context.txt
# JSON output to capture the file ID
xeroctl files --upload data.jsonl --purpose batch -o json
On success the CLI prints the new file ID, filename, purpose, size, and status. Capture the ID for use in batch creation or other API calls.
Tip: When creating a batch, the xeroctl batches --input command handles the upload step automatically. Use xeroctl files --upload when you need the file ID independently.
Download File Content
Download the raw content of a file to a local path. This is commonly used to retrieve batch output or error files after a batch completes.
# Download to a specific path
xeroctl files file-abc123 --download output.jsonl
# Download to a path under a subdirectory
xeroctl files file-abc123 --download ./results/batch-output.jsonl
The --download flag requires both a file ID (positional argument)
and a destination path. They cannot be combined with --delete or
--upload.
Delete a File
Delete a file from the platform. This is permanent and cannot be undone.
Use --dry-run to preview the operation.
# Delete a file
xeroctl files file-abc123 --delete
# Preview without deleting
xeroctl files file-abc123 --delete --dry-run
There is no confirmation prompt for file deletion. Use --dry-run
to verify the target before committing.
Purpose Values
The --purpose flag classifies a file and determines how it is
processed and retained by the platform.
| Value | Description |
|---|---|
batch |
Input or output file for the Batch API. Used with xeroctl batches --input. |
assistants |
General-purpose file for use as assistant context (default when --purpose is omitted). |
When listing, use --purpose to filter results to a specific
category. When uploading, it sets the purpose stored on the file record.
Options Reference
Full reference for all flags and options accepted by xeroctl files.
Action Flags (mutually exclusive)
| Flag / Option | Requires File ID | Description |
|---|---|---|
--delete |
Yes | Permanently delete the file. |
--download <path> |
Yes | Download the file content to the given local path. |
--upload <path> |
No | Upload a file from the given local path. Cannot be combined with a file ID argument. |
List / Upload Options
| Option | Description |
|---|---|
--purpose <value> |
Filter by purpose when listing, or set purpose when uploading. Default for upload: "assistants". |
--limit <n> |
Maximum number of results when listing. Default: 20. |
Examples
Upload a Batch Input File and Capture the ID
# Upload and capture file ID with jq
FILE_ID=$(xeroctl files --upload requests.jsonl --purpose batch -o json \
| jq -r '.id')
echo "Uploaded: $FILE_ID"
List and Download All Batch Output Files
# List batch files
xeroctl files --purpose batch
# Download a specific output file
xeroctl files file-output-abc123 --download batch-results.jsonl
Clean Up Old Files
# Preview deletion
xeroctl files file-abc123 --delete --dry-run
# Delete
xeroctl files file-abc123 --delete
