> ## Documentation Index > Fetch the complete documentation index at: https://docs.cirron.com/llms.txt > Use this file to discover all available pages before exploring further. # spool > Inspect local SDK trace spool files. # 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 ```bash theme={null} cirron spool inspect [--dir ] [--json] cirron spool flush [--dir ] cirron spool clear [--dir ] [--force] ``` ## Options | Option | Description | Default | | -------------- | ----------------------------------------- | --------------------------------------------- | | `--dir ` | 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. ```bash theme={null} # 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 ```json theme={null} { "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. ```bash theme={null} # 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). ```bash theme={null} # 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. ```bash theme={null} # 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 : 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 but failed to delete local spool file : . 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 ```bash theme={null} # 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 ```bash theme={null} # 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 ```bash theme={null} # See what's taking up space cirron spool inspect # Wipe after confirming upload cirron spool flush cirron spool clear --force ``` ## Related Commands * **cirron auth**: Manage authentication (required for `flush`) * **cirron status**: Check CLI status * **cirron config**: Manage CLI configuration (`apiUrl`, `timeout`, etc.)