cirron doctor

Print a single-command diagnostic of the user’s local Cirron setup: installed SDK extras, resolved config, local spool status, and platform connectivity. cirron doctor is designed as the first thing a user runs after pip install cirron-sdk, and as the standard artifact for support tickets (“run cirron doctor and send me the output”). The command is read-only and never mutates state. It works with no arguments, no API key, and no config file: each section reports what is present and what is missing rather than failing.

Usage

cirron doctor [--json] [--venv <path>] [--no-color] [--strict]

Options

Option	Description	Default
`--json`	Emit a machine-readable JSON object with the full report	off
`--venv <path>`	Inspect a specific Python environment instead of auto-detecting	auto-detected (see below)
`--no-color`	Disable ANSI color, regardless of TTY	off
`--strict`	Exit non-zero when no Python environment is detected	off

What Gets Reported

Environment

The Python environment being inspected. Resolution order (first hit wins):

$VIRTUAL_ENV (set by source .venv/bin/activate)
$CONDA_PREFIX (set by conda activate)
./.venv/ in the current working directory
./venv/ in the current working directory
Nothing found, dep sections are skipped

Pass --venv /path/to/.venv to override. Doctor reads Python’s version string from the venv’s pyvenv.cfg, so no Python process is ever spawned.

Dependency Sections

The installed cirron-sdk package is the source of truth: doctor parses the Requires-Dist lines in its METADATA file to discover which optional extras the SDK advertises and checks each one against site-packages. Results are grouped into:

Core: cirron-sdk, pydantic, pyyaml, requests. Any missing entry here counts as a broken install.
Core (optional): python-dotenv for .env auto-loading.
Frameworks: torch, tensorflow, transformers, scikit-learn. When installed, each advertises the SDK feature it unlocks (hooks available or ci.wrap() available).
Data: pandas, polars, datasets, etc. pandas is the default ci.load() backend.
Snapshots: safetensors, required for sampled or full snapshot capture.
Other extras: groups the installed SDK declares that this CLI version does not have friendly labels for (for example [s3], [azure], [postgres]). A note at the bottom suggests upgrading the CLI when this list is non-empty.

Every missing row carries the exact pip install 'cirron-sdk[group]' hint needed to install it.

Platform

Endpoint, authentication, and connectivity. Doctor prefers the CLI’s ~/.cirron/config.json (the file written by cirron auth login) and falls back to the SDK’s ~/.cirron/config.toml. The authSource field captures which layer supplied credentials:

cli: JWT from cirron auth login
sdk: api_key in ~/.cirron/config.toml
env: CIRRON_API_KEY env var
api: an API key is present but the origin was not tracked

When credentials are found, doctor sends GET /api/health with a 3-second timeout, records latency, and reads the platform’s health payload (status, version). When no credentials are present, doctor prints not configured without making any network call.

Local

The paths and presence of relevant config files:

~/.cirron/config.json (CLI auth)
~/.cirron/config.toml (SDK config)
cirron.yaml / cirron.yml / cirron.json discovered by walking upward from the current directory
.env in the current directory
Resolved output_dir with its resolution source (default, config.toml, env)

Spool

File count, total bytes, oldest/newest mtime, and free disk space for the directory at {output_dir}/spool/.

GPU

A single line from the CLI’s existing hardware detector. Silently omitted when no GPU is detected.

Example Output

Activated venv with the full SDK install:

cirron-cli 0.0.0
Python 3.13.5
Node v22.22.0
Platform: macOS 25.3.0 arm64

Environment:
  Source           VIRTUAL_ENV
  Root             /Users/alice/proj/.venv
  site-packages    /Users/alice/proj/.venv/lib/python3.13/site-packages

Core:
  cirron-sdk                [OK]  0.0.1
  pydantic                  [OK]  2.13.2
  PyYAML                    [OK]  6.0.3
  requests                  [OK]  2.33.1

Core (optional):
  python-dotenv             [OK]  1.2.2      .env file support

Frameworks:
  torch                     [OK]  2.6.0      hooks available
  tensorflow                [X]              pip install 'cirron-sdk[tensorflow]'
  transformers              [OK]  4.51.0     hooks available
  scikit-learn              [OK]  1.6.1      ci.wrap() available

Data:
  pandas                    [OK]  2.2.0      default ci.load() backend
  polars                    [X]              pip install 'cirron-sdk[polars]'
  datasets                  [X]              pip install 'cirron-sdk[hf]'

Snapshots:
  safetensors               [X]              pip install 'cirron-sdk[safetensors]'

Platform:
  Endpoint         https://app.cirron.com (from ~/.cirron/config.json)
  Authentication   [OK]  CLI
  Workspace        cirron-dev
  Connection       [OK]  healthy, latency 45ms
  Platform version 0.0.1

Local:
  CLI config       /Users/alice/.cirron/config.json (authenticated)
  SDK config       /Users/alice/.cirron/config.toml (not found)
  Output dir       ./.cirron/ (default)

Spool:
  Directory        /Users/alice/proj/.cirron/spool
  Contents         2 file(s), 14.3 KB
  Disk free        217.7 GB

GPU:
  Apple M2 Max

Environment looks good.

JSON Output

cirron doctor --json > doctor.json

{
  "cli": { "version": "0.0.0", "userAgent": "cirron-cli/0.0.0" },
  "node": { "version": "v22.22.0" },
  "platform": { "system": "darwin", "release": "25.3.0", "arch": "arm64", "pretty": "macOS 25.3.0 arm64" },
  "pythonEnv": {
    "found": true,
    "root": "/Users/alice/proj/.venv",
    "source": "VIRTUAL_ENV",
    "sitePackages": "/Users/alice/proj/.venv/lib/python3.13/site-packages",
    "pythonVersion": "3.13.5",
    "pythonExecutable": null,
    "checked": [],
    "reason": null
  },
  "sdk": {
    "installed": true,
    "version": "0.0.1",
    "metadataPath": "/Users/alice/proj/.venv/lib/python3.13/site-packages/cirron_sdk-0.0.1.dist-info/METADATA"
  },
  "deps": {
    "rowsBySection": {
      "core":         [ { "distName": "cirron-sdk",   "installed": true,  "version": "0.0.1" } ],
      "core_optional":[ { "distName": "python-dotenv","installed": true,  "version": "1.2.2" } ],
      "frameworks":   [ { "distName": "torch",        "installed": true,  "version": "2.6.0" } ],
      "data":         [ { "distName": "pandas",       "installed": true,  "version": "2.2.0" } ],
      "snapshots":    [ { "distName": "safetensors",  "installed": false, "version": null   } ],
      "other":        []
    },
    "missingCore": [],
    "unknownExtras": []
  },
  "platformApi": {
    "configured": true,
    "endpoint": "https://app.cirron.com",
    "endpointSource": "cli",
    "workspaceId": null,
    "authSource": "cli",
    "reachable": true,
    "latencyMs": 45,
    "status": "healthy",
    "platformVersion": "0.0.1",
    "error": null,
    "message": "healthy, latency 45ms"
  },
  "spool": {
    "dir": "/Users/alice/proj/.cirron/spool",
    "exists": true,
    "files": 2,
    "bytes": 14336,
    "oldestMtime": "2026-04-20T15:00:00.000Z",
    "newestMtime": "2026-04-20T15:12:00.000Z",
    "diskFreeBytes": 233745870848
  },
  "exitCode": 0
}

Exit Codes

Code	Meaning
`0`	All core deps present, and platform is either reachable or not configured (valid for standalone use)
`1`	A core dep is missing (broken install), or the configured platform is unreachable or reports `unhealthy`, or `cirron-sdk` itself is not installed in the target environment. `--strict` also returns 1 when no Python environment is detected.

Missing optional extras never cause a non-zero exit. The whole point of doctor is to report them without failing.

How It Works

Doctor inspects your Python environment without ever spawning python. Packages installed via pip drop a {name}-{version}.dist-info/METADATA file in site-packages/, which is a plain RFC 822 text file. Doctor reads those files directly: for cirron-sdk, it parses the Requires-Dist lines to discover the SDK’s extras groups; for every package in the report, it reads Name and Version from the same file. This approach has three benefits:

The expected-dep list is always fresh, baked into whatever SDK version the user has installed. A newer SDK with new extras will surface under “Other extras” even on an older CLI.
No subprocess, no shell-escaping, no cross-platform python3 vs python discovery.
Fast: doctor finishes in well under a second even on a venv with dozens of deps.

Meta-extras that re-aggregate other groups (like [all] or [sql]) are filtered to keep the report clean.

Examples

First-Run Setup Check

python -m venv .venv
source .venv/bin/activate
pip install cirron-sdk
cirron doctor

Confirms the SDK is installed correctly and highlights every optional extra you have not installed yet.

CI Pipeline

- name: Validate Cirron environment
  run: cirron doctor --json > doctor-report.json
- name: Upload report
  uses: actions/upload-artifact@v4
  with:
    name: cirron-doctor
    path: doctor-report.json

Artifact the JSON report on every build. A non-zero exit fails the job.

Support Ticket

cirron doctor > support.txt

One file captures the CLI version, Python version, OS, installed SDK deps with versions, config sources, platform reachability, and spool state. Attach it when opening an issue.

Troubleshooting a Specific Venv

cirron doctor --venv /path/to/other/.venv

Point doctor at any environment, not just the currently-activated one. Useful when comparing a working dev setup to a broken CI image.

cirron auth status — Show authentication state (doctor includes a compact version of this)
cirron info —diagnostics — CLI-side diagnostic (auth, config, connectivity) as opposed to doctor’s SDK-environment focus
cirron spool inspect — Detailed per-file view of the spool; doctor only reports counts and totals
ci.deps(): In-process equivalent for scripts and library code. Reports installed extras and raises CirronDependencyError listing missing ones when called with required names

Cirron CLI

Commands

Utils

Templates

doctor

cirron doctor

Usage

Options

What Gets Reported

Environment

Dependency Sections

Platform

Local

Spool

GPU

Example Output

JSON Output

Exit Codes

How It Works

Examples

First-Run Setup Check

CI Pipeline

Support Ticket

Troubleshooting a Specific Venv

Cirron CLI

Commands

Utils

Templates

Documentation Index

​cirron doctor

​Usage

​Options

​What Gets Reported

​Environment

​Dependency Sections

​Platform

​Local

​Spool

​GPU

​Example Output

​JSON Output

​Exit Codes

​How It Works

​Examples

​First-Run Setup Check

​CI Pipeline

​Support Ticket

​Troubleshooting a Specific Venv

​Related Commands

cirron doctor

Usage

Options

What Gets Reported

Environment

Dependency Sections

Platform

Local

Spool

GPU

Example Output

JSON Output

Exit Codes

How It Works

Examples

First-Run Setup Check

CI Pipeline

Support Ticket

Troubleshooting a Specific Venv

Related Commands