# Command line (/docs/python/cli) The `tracepanel` package installs the `tracepanel` command. Run it from your project's directory, so it finds the project's settings and store. | Command | What it does | | --- | --- | | `tracepanel run` | Runs a command with Tracepanel on. | | `tracepanel dev` | Runs the agent in the foreground and serves the console. | | `tracepanel config` | Prints the settings in effect and where each one comes from. | | `tracepanel clear` | Deletes every stored trace, log, query, email and issue. | | `tracepanel mcp` | Runs an MCP server for AI coding agents. | | `tracepanel agent` | Runs the Tracepanel agent with its own flags. | | `tracepanel version` | Prints the version. | ## tracepanel run [#tracepanel-run] ```bash tracepanel run [--set name=value]... ``` `tracepanel run` starts any command with Tracepanel on. You don't change anything in the project. It sets `TRACEPANEL_ENABLED=1`, so Tracepanel is on even when `DEBUG` is off. Then it sets up each framework and library as your code imports it: - Django gets `tracepanel.django` in `INSTALLED_APPS`. - A FastAPI, Starlette, Flask or Falcon app gets Tracepanel when it is created. - Every library integration turns on as your code imports its library, so a worker or a script needs no framework. That covers the task queues, SQLAlchemy, the database drivers, the HTTP clients, Redis, MongoDB, Strawberry, OpenTelemetry and logging. ```bash tracepanel run python manage.py runserver # Django tracepanel run uvicorn app.main:app # FastAPI, Starlette tracepanel run flask --app app run # Flask tracepanel run gunicorn app:app # Falcon tracepanel run celery -A app worker # a Celery worker ``` `--set name=value` sets one setting for this run. Repeat it for more settings. It sets the matching `TRACEPANEL_` variable, and it rejects a name that isn't a setting: ```bash tracepanel run --set slow_sql_ms=50 --set capture_locals=false python manage.py runserver ``` A `--` before the command ends the flags of `tracepanel run`. ## tracepanel dev [#tracepanel-dev] ```bash tracepanel dev [--host 127.0.0.1] [--port 8765] ``` `tracepanel dev` runs the agent in the foreground. The agent receives the project's traces and serves the console on http://127.0.0.1:8765/, with no app running. Without this command, the first trace starts the agent in the background. Use it to watch the agent's output, or to read the traces after your app has stopped. A project has one agent at a time. If your app has already started one in the background, `tracepanel dev` stops and says that an agent already runs for the store. An agent that the app started exits after 30 minutes unused. Run `tracepanel dev` before you start the app, or open the console at the link in the terminal instead. The agent also takes OpenTelemetry spans over OTLP/HTTP on `127.0.0.1:4318`. See [tracepanel agent](#tracepanel-agent). `--host` and `--port` choose the console's address: ```bash tracepanel dev --port 9000 ``` `EXPLAIN` works here while your app is running, because the agent asks your app to run it. Switching the user needs your app's sessions, so use it at `/__tracepanel__/` on your app. ## tracepanel config [#tracepanel-config] ```bash tracepanel config ``` `tracepanel config` prints every setting with its value and the place that set it. Then it prints each integration and its state: on, not installed, or turned off by its setting. ```text slow_sql_ms 200 pyproject.toml [tool.tracepanel] capture_locals false env TRACEPANEL_CAPTURE_LOCALS ... integrations logging on Database drivers on HTTP clients on Redis off: redis_enabled MongoDB off: not installed Celery on DRF on (Django apps only) ``` The command reads `tracepanel.toml`, `pyproject.toml` and the `TRACEPANEL_` variables. It doesn't read Django's settings, so the `TRACEPANEL` dict, `DEBUG` and `BASE_DIR` don't show in its output. If a setting has a wrong name or type, the command prints the error and the place the value came from. See [Configuration](/docs/python/configuration). ## tracepanel clear [#tracepanel-clear] ```bash tracepanel clear [--yes] [--dir DIR] ``` `tracepanel clear` deletes every stored trace, log, query, email and issue of the project. It asks for confirmation first, and the deletion can't be undone. The agent does the deletion, as the console's button does, so the command starts the agent if it isn't running. `--yes`, or `-y`, skips the confirmation. `--dir` names the store directory. The default is the `dir` setting, `.tracepanel`, in the project's directory. ```bash tracepanel clear --yes ``` ## tracepanel mcp [#tracepanel-mcp] ```bash tracepanel mcp [--values] ``` `tracepanel mcp` runs an MCP server on stdin and stdout for AI coding agents. A coding agent reads the project's traces and issues through it. The answers leave out SQL parameters and local variables. `--values` includes them, with secrets masked. ```bash claude mcp add --scope project tracepanel -- tracepanel mcp ``` If `tracepanel` is in a virtual environment, give the full path of its `tracepanel` command, or `uv run tracepanel mcp` in a uv project. See [AI coding agents](/docs/ai-agents). ## tracepanel agent [#tracepanel-agent] ```bash tracepanel agent [flags] ``` `tracepanel agent` runs `tracepanel-agent`, the program the SDK installs. It passes the store directory of the current project as `--dir`, unless you pass `--dir` yourself. If the program is missing, reinstall `tracepanel` or point the `TRACEPANEL_AGENT_BIN` variable at it. The agent takes these flags: | Flag | What it does | | --- | --- | | `--dir DIR` | The project's store directory. The default is `.tracepanel`. | | `--listen ADDRESS` | Where SDKs connect: `unix` for a unix socket, or `tcp:HOST:PORT`, such as `tcp:127.0.0.1:0`. The default is a unix socket, except on Windows. | | `--serve HOST:PORT` | Also serves the console, its UI and API, such as `127.0.0.1:8765`. Port 0 picks any free port. | | `--otlp HOST:PORT` | Takes OpenTelemetry spans over OTLP/HTTP at this address. The default is `127.0.0.1:4318`, where exporters send them unless told otherwise. `--otlp off` turns it off. If the port is in use, the agent says so and runs without it. | | `--idle-exit SECONDS` | Exits after this many seconds unused. | | `--record DIR` | Also saves each trace as received, before analysis, to `DIR/.json`. | | `--version`, `-V` | Prints the agent's version. | | `--help`, `-h` | Prints the agent's flags. | | `mcp [--values]` | Runs the MCP server, as `tracepanel mcp` does. | To run the agent by hand, with the console on http://127.0.0.1:8765/: ```bash tracepanel agent --serve 127.0.0.1:8765 ``` ## tracepanel version [#tracepanel-version] ```bash tracepanel version ``` `tracepanel version` prints the version of the `tracepanel` package. `tracepanel --version` does the same.