> ## 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. # doctor > Diagnose the local Cirron SDK and CLI environment. # 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 ```bash theme={null} cirron doctor [--json] [--venv ] [--no-color] [--strict] ``` ## Options | Option | Description | Default | | --------------- | --------------------------------------------------------------- | ------------------------- | | `--json` | Emit a machine-readable JSON object with the full report | off | | `--venv ` | 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): 1. `$VIRTUAL_ENV` (set by `source .venv/bin/activate`) 2. `$CONDA_PREFIX` (set by `conda activate`) 3. `./.venv/` in the current working directory 4. `./venv/` in the current working directory 5. 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 ```bash theme={null} cirron doctor --json > doctor.json ``` ```json theme={null} { "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: 1. 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. 2. No subprocess, no shell-escaping, no cross-platform `python3` vs `python` discovery. 3. 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 ```bash theme={null} 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 ```yaml theme={null} - 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 ```bash theme={null} 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 ```bash theme={null} 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. ## Related Commands * **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()`](/sdk/reference/deps)**: In-process equivalent for scripts and library code. Reports installed extras and raises `CirronDependencyError` listing missing ones when called with required names