> ## Documentation Index
> Fetch the complete documentation index at: https://www.botgauge.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Reference for the botgauge command: instrument, setup, doctor, probe, and help. Flags, exit codes, and the botg alias.

Installing the SDK adds the `botgauge` command. `botg` is a short alias, so `botg doctor` and `botgauge doctor` run the same command. `botgauge help` lists every command your installed BotGauge packages provide.

## botgauge instrument

Launches your app with tracing turned on, with no code changes. See [Zero-code instrumentation](https://www.botgauge.com/docs/tracing/zero-code.md) for details.

```bash terminal theme={null}
botgauge instrument [--env-file FILE] [--strict] <command> [args...]
```

| Flag | Effect |
| - | - |
| `--env-file FILE` | Reads settings from a `.env` file. Variables already set win. The flag can repeat. An unreadable file stops the launcher before your app starts. |
| `--strict` | Refuses to start your app on instrumentation problems, including frameworks that would be traced at a version that isn't verified. Exits 1. Same as `BOTGAUGE_STRICT=1`. |

```bash terminal theme={null}
botgauge instrument python your_app.py
botgauge instrument --env-file .env python your_app.py
botgauge instrument --strict python your_app.py
```

## botgauge setup

Finds the frameworks in your environment and recommends or installs the BotGauge extra for each.

```bash terminal theme={null}
# recommend producer extras for installed frameworks (installs nothing)
botgauge setup --detect

# install them, pinned to your installed BotGauge version
botgauge setup --install
```

`setup` finds frameworks without importing them. It installs with `pip`, or `uv` in an environment created by `uv venv`.

## botgauge doctor

Prints a read-only report of the current process: the tracer provider, instrumentors, and warnings.

```bash terminal theme={null}
botgauge doctor
botgauge doctor --json
```

`doctor` only sees the process it runs in, so a separate `botgauge doctor` can't tell you what your app turned on. To see that, read your app's startup log, or call `doctor.report()` inside the app.

```python app.py theme={null}
from botgauge.tracing import doctor

report = doctor.report()
```

Frameworks at versions that aren't verified are under `["instrumentors"]["not_verified"]`, with the reason.

## botgauge probe

Sends one real diagnostic span and exits 0 only if ingest accepts it.

```bash terminal theme={null}
BOTGAUGE_API_KEY="<your key>" botgauge probe --endpoint https://api.botgauge.com/v1/traces
```

`probe` creates a real trace. When ingest accepts the span, it prints `probe: OTLP ingest accepted the diagnostic span.` When the span is rejected or times out, it prints `probe: ingest acceptance not confirmed` and exits 1.

## Exit codes

| Command | Exit code | Meaning |
| - | - | - |
| `probe` | 0 | Ingest accepted the diagnostic span |
| `probe` | 1 | The span was rejected, or acceptance timed out |
| `instrument --strict` | 1 | The app was not started because of a problem such as an unverified version |

> [!NOTE]
>
> The SDK is an early release (0.x). Public API shapes may still change before 1.0.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.