CLI reference - BotGauge Docs

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 for details.

terminal

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`.

terminal

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.

terminal

# 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.

terminal

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.

app.py

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.

terminal

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

The SDK is an early release (0.x). Public API shapes may still change before 1.0.

​botgauge instrument

​botgauge setup

​botgauge doctor

​botgauge probe

​Exit codes

botgauge instrument

botgauge setup

botgauge doctor

botgauge probe

Exit codes