Command line

The tracepanel package installs the tracepanel command. Run it from your project's directory, so it finds the project's settings and store.

tracepanel runCopy Anchor Link

tracepanel run [--set name=value]... <command>

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.

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_<NAME> variable, and it rejects a name that isn't a setting:

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 devCopy Anchor Link

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.

--host and --port choose the console's address:

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 configCopy Anchor Link

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.

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_<NAME> 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.

tracepanel clearCopy Anchor Link

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.

tracepanel clear --yes

tracepanel mcpCopy Anchor Link

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.

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.

tracepanel agentCopy Anchor Link

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:

To run the agent by hand, with the console on http://127.0.0.1:8765/:

tracepanel agent --serve 127.0.0.1:8765

tracepanel versionCopy Anchor Link

tracepanel version

tracepanel version prints the version of the tracepanel package. tracepanel --version does the same.