xeroctl files - Xerotier

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 single file
xeroctl files --upload <dir> -r: Upload a directory tree

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.

bash

                    # 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

# Filter by relative_path prefix (set during directory uploads)
xeroctl files --prefix docs/

# Render the listing as an ASCII directory tree
xeroctl files --tree

# JSON output (-o is a global flag; see xeroctl CLI overview)
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. Pagination is bounded by the configured limit; a cursor flag is not exposed by this CLI.

--prefix filters the listing on each file's stored relative_path, which is populated when files are uploaded as part of a directory tree (see Upload a Directory).

--tree renders the result set as an ASCII directory tree using box-drawing connectors (+--, |--), with each leaf annotated with its byte size. Files without a relative_path are rendered at the root by filename. The --prefix and --tree flags are list-only and cannot be combined with --upload.

The global --watch flag is supported in list mode and will re-run the listing on an interval; see the xeroctl CLI overview for global flags.

Get File

Show the metadata for a specific file by its ID.

bash

                    # Human-readable key-value output
xeroctl files file-9f1b3c2d4e5f6071829a3b4c

# JSON output (full record, including expires_at and x_relative_path)
xeroctl files file-9f1b3c2d4e5f6071829a3b4c -o json
                

The human-readable detail view shows: ID, Filename, Purpose, Status, Size, and Created time. The server response also carries expires_at and x_relative_path fields; these are not surfaced by the formatted view today. Use -o json to read them.

Upload a File

Upload a local file to the platform. --purpose classifies the file so the server routes and retains it correctly (see Purpose Values for the accepted set). If --purpose is omitted, the CLI sends assistants by default.

bash

                    # 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. --dry-run does not gate --upload; see Options Reference for its exact scope.

Upload a Directory

Pass a directory path to --upload together with -r/--recursive to walk the tree and upload every regular file beneath it. The CLI computes a relative_path for each entry from its location under the root and forwards that path to the server, where it is stored on the file record and made queryable via --prefix and --tree in list mode.

Required: Directory uploads require -r. Without it the CLI exits with: --upload of a directory requires --recursive (-r).

bash

                    # Upload every file under ./docs, recursively
xeroctl files --upload ./docs -r --purpose assistants

# Include hidden entries (dotfiles, .config, etc.)
xeroctl files --upload ./docs -r --include-hidden

# Follow symbolic links (skipped by default)
xeroctl files --upload ./docs -r --follow-symlinks

# Strip an absolute prefix from each stored relative_path
xeroctl files --upload /home/me/project/docs -r \
  --strip-prefix /home/me/project
                

// per-entryOutput

Directory uploads print one line per entry plus a summary:

output

                    [OK]   guides/getting-started.md  4.2 KB
[OK]   guides/upload.md           2.1 KB
[FAIL] guides/broken.bin          (uploadFailed(...))

2 uploaded, 1 failed.
                

The command exits non-zero when one or more entries fail. Entries are uploaded serially; no concurrency flag is exposed.

// flagsDirectory Flags

Flag / Option	Description
`-r`, `--recursive`	Required when `--upload` points at a directory. Walks the tree and uploads every regular file.
`--include-hidden`	Include hidden entries (names starting with `.`) when walking a directory. Skipped by default.
`--follow-symlinks`	Follow symbolic links when walking a directory. Skipped by default to avoid cycles.
`--strip-prefix <abs>`	Strip the given absolute path prefix from each computed `relative_path` before uploading. Useful when the upload root sits deep under your workspace and you want shorter stored paths.

After upload, the stored tree can be inspected with xeroctl files --tree or filtered with xeroctl files --prefix <path>/.

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.

bash

                    # Download to a specific path
xeroctl files file-9f1b3c2d4e5f6071829a3b4c --download output.jsonl

# Download to a path under a subdirectory
xeroctl files file-9f1b3c2d4e5f6071829a3b4c --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 the global --dry-run flag to preview the operation.

bash

                    # Delete a file
xeroctl files file-9f1b3c2d4e5f6071829a3b4c --delete

# Preview without deleting
xeroctl files file-9f1b3c2d4e5f6071829a3b4c --delete --dry-run
                

There is no confirmation prompt for file deletion. Use --dry-run to verify the target before committing. The flag is honored only by --delete; --upload and --download execute over the wire regardless. See Options Reference for the canonical statement.

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).
`vision`	Image attachments referenced by vision-capable models. Text-only deployments do not consume this class today.
`user_data`	Arbitrary user-supplied data files (datasets, exports, attachments).
`fine-tune`	Training corpora for fine-tuning workflows.

When listing, use --purpose to filter results to a specific category. When uploading, it sets the purpose stored on the file record. The CLI forwards the string as-is; the server validates it against the table above and rejects unknown values with HTTP 400.

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`. See Purpose Values for accepted values.
`--limit <n>`	Maximum number of results when listing. Default: 20.
`--prefix <p>`	List mode only. Filter results to files whose stored `relative_path` starts with the given prefix. Mutually exclusive with `--upload`.
`--tree`	List mode only. Render the result set as an ASCII directory tree. Mutually exclusive with `--upload`.

Directory Upload Flags

Flag / Option	Description
`-r`, `--recursive`	Required when `--upload` targets a directory. Walks the tree and uploads each regular file with a computed `relative_path`.
`--include-hidden`	Include hidden entries (names starting with `.`) during the walk.
`--follow-symlinks`	Follow symbolic links during the walk. Skipped by default.
`--strip-prefix <abs>`	Strip the given absolute path prefix from each computed `relative_path` before uploading.

Global Flags Used by `files`

The following flags are defined globally on xeroctl (see the CLI overview) and are referenced by the files subcommand:

Flag	Description
`-o <format>`	Output format. Use `-o json` to emit machine-readable records on list, get, and upload.
`--watch`	List mode only. Re-runs the listing on an interval.
`--dry-run`	Honored by `--delete` only. Has no effect on `--upload` or `--download`.
`--quiet`	Suppress spinners and per-entry output.

Examples

// 01Upload a Batch Input File and Capture the ID

bash

                    # 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"
                

// 02List and Download All Batch Output Files

bash

                    # List batch files
xeroctl files --purpose batch

# Download a specific output file
xeroctl files file-9f1b3c2d4e5f6071829a3b4c --download batch-results.jsonl
                

// 03Upload a Documentation Tree and Inspect It

bash

                    # Upload every file beneath ./docs, stripping the workspace prefix
xeroctl files --upload ./docs -r \
  --purpose assistants \
  --strip-prefix "$(pwd)"

# Inspect the resulting tree on the server
xeroctl files --tree

# Filter to one subtree
xeroctl files --prefix docs/guides/
                

// 04Clean Up Old Files

bash

                    # Preview deletion (--dry-run is honored for --delete only)
xeroctl files file-9f1b3c2d4e5f6071829a3b4c --delete --dry-run

# Delete
xeroctl files file-9f1b3c2d4e5f6071829a3b4c --delete
                

Overview

List Files

Get File

Upload a File

Upload a Directory

// per-entryOutput

// flagsDirectory Flags

Download File Content

Delete a File

Purpose Values

Options Reference

Action Flags (mutually exclusive)

List / Upload Options

Directory Upload Flags

Global Flags Used by files

Examples

// 01Upload a Batch Input File and Capture the ID

// 02List and Download All Batch Output Files

// 03Upload a Documentation Tree and Inspect It

// 04Clean Up Old Files

xeroctl CLI

xeroctl batches

Global Flags Used by `files`