cirron spool

Manage the local spool directory where the Cirron Python SDK writes trace batches while ci.profile() is active. Spool files accumulate in ./.cirron/spool/ and contain JSON batches of spans and marks produced by your training or inference code. The spool command group is the setup path for external runs: laptops, notebooks, or customer servers that aren’t on platform-managed compute. It lets you see what the SDK has buffered locally, push those batches to the platform, or reclaim disk by clearing them.

Subcommands

cirron spool inspect: List spool files with sizes and timestamps
cirron spool flush: Upload buffered batches to the platform
cirron spool clear: Delete local spool files

Usage

cirron spool inspect [--dir <path>] [--json]
cirron spool flush   [--dir <path>]
cirron spool clear   [--dir <path>] [--force]

Options

Option	Description	Default
`--dir <path>`	Override the spool directory	`./.cirron/spool` (current working directory)
`--json`	Emit machine-readable JSON (inspect only)	—
`--force`	Skip the confirmation prompt (clear only)	—

Subcommand Details

Inspect the Spool

List every batch file in the spool with its timestamp and size, plus a header summary and oldest/newest footer.

# Inspect the default ./.cirron/spool directory
cirron spool inspect

# Inspect a custom directory (e.g. a saved-off run)
cirron spool inspect --dir /path/to/runs/run-42/.cirron/spool

# Machine-readable JSON output
cirron spool inspect --json

Example Output

Spool: /Users/alice/projects/resnet50/.cirron/spool  (3 files, 2.51 MB)
┌──────────────────────────┬─────────┬────────────────────────────────────────────────────────────┐
│ Timestamp                │    Size │ File                                                       │
├──────────────────────────┼─────────┼────────────────────────────────────────────────────────────┤
│ 2026-04-18T04:29:58.051Z │ 2.50 MB │ 01776486598051509000-446a507b2456443f923f85774a0854e3.json │
│ 2026-04-18T04:29:58.073Z │    6 KB │ 01776486598073663000-b38212eb3835460ab6f2345a7ee3fd4c.json │
│ 2026-04-18T04:30:01.204Z │    9 KB │ 01776486601204118000-ff11aa22cc334455667788999aabbccdd.json │
└──────────────────────────┴─────────┴────────────────────────────────────────────────────────────┘
Oldest: 2026-04-18T04:29:58.051Z   Newest: 2026-04-18T04:30:01.204Z

Empty Spool Output

No spool files found in /Users/alice/projects/resnet50/.cirron/spool

JSON Output

{
  "dir": "/Users/alice/projects/resnet50/.cirron/spool",
  "files": 2,
  "totalBytes": 2633547,
  "oldest": {
    "name": "01776486598051509000-446a507b2456443f923f85774a0854e3.json",
    "createdNs": "1776486598051509000",
    "iso": "2026-04-18T04:29:58.051Z"
  },
  "newest": {
    "name": "01776486598073663000-b38212eb3835460ab6f2345a7ee3fd4c.json",
    "createdNs": "1776486598073663000",
    "iso": "2026-04-18T04:29:58.073Z"
  },
  "entries": [
    { "name": "01776486598051509000-446a507b2456443f923f85774a0854e3.json", "size": 2633103, "createdNs": "1776486598051509000", "iso": "2026-04-18T04:29:58.051Z" },
    { "name": "01776486598073663000-b38212eb3835460ab6f2345a7ee3fd4c.json", "size": 444,     "createdNs": "1776486598073663000", "iso": "2026-04-18T04:29:58.073Z" }
  ]
}

Flush the Spool

Upload every batch file to the platform’s trace ingest endpoint, then delete each file after it’s acknowledged. Files are sent in oldest-first order. Batches are gzip-compressed when larger than 1 KB.

# Flush the default directory
cirron spool flush

# Flush a saved directory after travelling between networks
cirron spool flush --dir ./archive/.cirron/spool

Flush uses the credentials stored by cirron auth login (~/.cirron/config.json). Before sending any batch, the CLI verifies your token is still valid and transparently refreshes it if it’s close to expiry. If verification returns 401/403, the flush is aborted with a prompt to re-authenticate. Each upload has a request timeout (governed by config.timeout) and retries up to three times on transient failures (5xx, 429, network errors) with exponential backoff. Rate-limited responses respect the Retry-After header.

Example Output

Uploaded: 2  Failed: 0  Skipped: 0

Partial Failure

If a fatal error occurs mid-flush (e.g. an authentication issue or an unrecoverable 4xx), remaining batches stay in the spool and can be retried on the next run:

Error: Auth rejected (401) for 01776486598051509000-446a507b2456443f923f85774a0854e3.json. Run cirron auth login.
Warning: Stopping flush; 1 batch left in spool.
Uploaded: 0  Failed: 1  Skipped: 1

Missing Ingest Route

If the platform you’re pointing at doesn’t expose /api/traces yet, flush fails fast with a clear message and leaves your spool intact:

Error: Ingest route /api/traces not available on https://app.cirron.com (404). Platform may not have shipped the route yet.

Clear the Spool

Delete every batch file in the spool directory. By default you’re shown a summary and asked to confirm; use --force to skip the prompt (useful in scripts).

# Interactive clear
cirron spool clear

# Non-interactive clear
cirron spool clear --force

# Clear a specific directory
cirron spool clear --dir ./archive/.cirron/spool

Confirmation Prompt

? Delete 3 spool files (2.51 MB) from /Users/alice/projects/resnet50/.cirron/spool? (y/N)

Example Output

Success: Deleted 3 spool files.

How It Works

The Python SDK writes spool files when ci.profile() is active. Each file is a JSON batch containing spans and marks from one flush interval (roughly 1 second of runtime). File names encode a nanosecond-precision timestamp plus a batch ID, which the CLI parses to present ordered results without reading each file’s contents. Spool files are the public local artifact of the SDK. They work standalone and can be consumed by third-party tools. Flushing to the platform is optional; many teams run profilers on disconnected laptops or air-gapped machines and simply archive the spool directory. The CLI’s spool commands are a lightweight inspection surface:

inspect shows the file-system inventory without parsing batch contents.
flush uploads exactly the JSON the SDK produced, no transformation.
clear is a plain directory delete.

For rich content viewing (flamegraphs, scope trees, mark plots), use cirron traces view instead.

Authentication

spool flush requires CLI authentication. inspect and clear are offline operations.

# Authenticate first
cirron auth login

# Then flush
cirron spool flush

If no credentials are found, flush aborts with:

Error: Not authenticated. Run cirron auth login first.

Error Handling

Common Errors

Not Authenticated

Error: Not authenticated. Run cirron auth login first.

Solution: Run cirron auth login.

Auth Expired

Error: Authentication invalid. Run cirron auth login first.

Solution: The CLI attempted a silent token refresh and the refresh token itself has expired. Re-authenticate with cirron auth login.

Upload Timeout

Error: Network error uploading <file>: timed out after 30000ms

Solutions: Check your network, then re-run cirron spool flush. The failed batch remains on disk and will be retried.

Local Unlink Failure

Error: Uploaded <file> but failed to delete local spool file <path>: <reason>. It may be re-uploaded on next flush.

Solutions: Check file-system permissions on the spool directory. The batch was successfully ingested; you can safely delete the local file manually.

Examples

Disconnected Laptop Workflow

# Train on a plane — no network needed
python train.py

# Back online: check what's queued
cirron spool inspect

# Push to platform
cirron auth login
cirron spool flush

Archive and Ship a Spool

# Copy the spool to a shared location
cp -r .cirron /mnt/shared/runs/run-42

# Later, from another machine
cirron spool inspect --dir /mnt/shared/runs/run-42/.cirron/spool
cirron spool flush   --dir /mnt/shared/runs/run-42/.cirron/spool

Reclaim Disk

# See what's taking up space
cirron spool inspect

# Wipe after confirming upload
cirron spool flush
cirron spool clear --force

cirron auth: Manage authentication (required for flush)
cirron status: Check CLI status
cirron config: Manage CLI configuration (apiUrl, timeout, etc.)

​cirron spool

​Subcommands

​Usage

​Options

​Subcommand Details

​Inspect the Spool

​Example Output

​Empty Spool Output

​JSON Output

​Flush the Spool

​Example Output

​Partial Failure

​Missing Ingest Route

​Clear the Spool

​Confirmation Prompt

​Example Output

​How It Works

​Authentication

​Error Handling

​Common Errors

​Not Authenticated

​Auth Expired

​Upload Timeout

​Local Unlink Failure

​Examples

​Disconnected Laptop Workflow

​Archive and Ship a Spool

​Reclaim Disk

​Related Commands

cirron spool

Subcommands

Usage

Options

Subcommand Details

Inspect the Spool

Example Output

Empty Spool Output

JSON Output

Flush the Spool

Example Output

Partial Failure

Missing Ingest Route

Clear the Spool

Confirmation Prompt

Example Output

How It Works

Authentication

Error Handling

Common Errors

Not Authenticated

Auth Expired

Upload Timeout

Local Unlink Failure

Examples

Disconnected Laptop Workflow

Archive and Ship a Spool

Reclaim Disk

Related Commands