Ironbee python devtools cli
Skill ironbee-ai/ironbee-devtools-skills/skills/ironbee-python-devtools-cli
Skills for IronBee DevTools MCP/CLI
npx -y skills add ironbee-ai/ironbee-devtools-skills --skill ironbee-python-devtools-cliAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
CLI for debugging running Python processes with non-blocking inspection via debugpy (Debug Adapter Protocol). Use when the user needs to attach to a Python process (already-listening debugpy, PID injection, process name, or Docker), set tracepoints/logpoints/exceptionpoints, capture call stacks and local variables, dump all thread stacks (deadlock/GIL diagnosis), read stdout/stderr logs, capture the process's outbound HTTP requests (egress) with W3C trace-context injection, or run reusable scenarios. Requires daemon and `debugpy` installed in the target's Python environment; connect before other debug commands. Also covers the creds-gated Jira and Linear issue-tracker domains: fetch/search issues, download attachments, attach evidence, comment, transition/set state, and report verification results back to the tracker.
SKILL.md
11.3 KB, as published. Nobody here has run it
IronBee Python DevTools CLI
Command-line interface for non-blocking debugging of running Python processes. Part of IronBee DevTools. Connects via debugpy over the Debug Adapter Protocol (DAP) and provides tracepoints, logpoints, exceptionpoints, watch expressions, and a Python-specific all-threads stack dump — without pausing execution (probes capture state and immediately resume).
Runtime prerequisite: the target's Python environment must have debugpy installed (pip install debugpy). It is a prerequisite in the target process, not on the machine running this CLI.
Installation
# Install this skill (skills.sh)
npx skills add ironbee-ai/ironbee-devtools-skills
# Install the CLI binary (same package as the rest of IronBee DevTools)
npm install -g @ironbee-ai/devtools
Port note
All IronBee DevTools CLIs default to daemon port 2020. If you want multiple daemons running at once, start the python daemon on a different port (convention: browser 2020, node 2021, backend 2022, android 2023, terminal 2024, python 2025) and pass --port to every python CLI call:
PLATFORM=python ironbee-python-devtools-cli daemon start --port 2025
ironbee-python-devtools-cli --port 2025 debug connect --host 127.0.0.1 --debugpy-port 5678
Quick Start
# 0. Start the target with debugpy listening (no code changes needed):
# python -m debugpy --listen 127.0.0.1:5678 app.py
# 1. Start daemon (if not running)
ironbee-python-devtools-cli daemon start
# 2. Connect (already-listening debugpy)
ironbee-python-devtools-cli --session-id my-debug debug connect --host 127.0.0.1 --debugpy-port 5678
# 3. Set a tracepoint on app.py line 42
ironbee-python-devtools-cli --session-id my-debug debug put-tracepoint \
--file "app.py" \
--line 42
# 4. Trigger the code path (e.g., make an API request to your app)
# 5. Get captured snapshots
ironbee-python-devtools-cli --session-id my-debug --json debug get-probe-snapshots
Global Options
| Option | Description | Default |
|---|---|---|
--port <number> | Daemon server port | 2020 |
--session-id <string> | Session for Python connection persistence | auto |
--json | Output as JSON (recommended for AI) | false |
--quiet | Suppress log messages | false |
--verbose | Enable debug output | false |
--timeout <ms> | Operation timeout | 30000 |
AI Agent Recommended:
ironbee-python-devtools-cli --json --quiet --session-id "debug-session" <command>
Tool Domains
| Domain | Description | Reference |
|---|---|---|
| debug | Connection, tracepoints, logpoints, exceptionpoints, watch, snapshots, logs, thread dump | debug |
| o11y | Outbound HTTP capture (get/clear-http-requests; in-process agent, proxy-free) + W3C trace context (new-trace-id, set/get-trace-context; traceparent injected on egress) | o11y |
| scenario | Reusable JS scripts (add, update, delete, list, search, run; scenario-run is a direct subcommand, optional typed params contract) — full surface registered on the python CLI; see the scenario reference. Note: the page binding is browser-only; inside a python scenario script only callTool is available. | |
| execute | Batch JavaScript execution (run execute; CLI and MCP) — see the execute reference. Note: the page binding is browser-only; on python only callTool is available inside the VM. | |
| jira | Jira issue tracker: intake, evidence, outcome, verification report (creds-gated shared domain; writes opt-in) | jira |
| linear | Linear issue tracker: intake, evidence, outcome, verification report (creds-gated shared domain; writes opt-in) | linear |
Jira / Linear are platform-agnostic shared issue-tracker domains (like scenario/execute) — registered on every platform CLI, but only when credentials are configured: jira needs JIRA_BASE_URL plus JIRA_EMAIL + JIRA_API_TOKEN (Cloud) or JIRA_PAT (Server/DC); linear needs LINEAR_API_KEY. Without creds the jira / linear subcommand group does not exist. Write tools (add-comment, attach-file, create/update-issue, transition-issue / set-state, link-issue, report-verification) additionally require JIRA_WRITE_ENABLED=true / LINEAR_WRITE_ENABLED=true (default off ⇒ read-only intake tools only). Close the loop after a verification run: ironbee-python-devtools-cli jira report-verification --key PROJ-123 --result pass --report "..." --artifacts ./artifacts/evidence.png (linear: same shape with --state instead of --transition). See jira / linear.
Connection Methods
Connect via debug connect with one of (none require modifying the target's source):
| Method | Option | Example |
|---|---|---|
| Already-listening debugpy (primary) | --host + --debugpy-port | --host 127.0.0.1 --debugpy-port 5678 |
| PID injection | --pid <number> | --pid 12345 |
| Process name | --process-name <pattern> | --process-name "app.py" |
| Docker container | --container-id or --container-name | --container-name my-api |
"Already-listening" means the target was started with python -m debugpy --listen host:port app.py or called debugpy.listen((host, port)). PID injection runs <python-path> -m debugpy --listen host:port --pid <pid> to inject debugpy into the running process (POSIX; needs same-user / ptrace permission); --python-path overrides the interpreter used for injection (default python3, env PYTHON_INTERPRETER). Docker injects via docker exec and connects to the published host port.
Defaults come from PYTHON_DEBUGPY_HOST (default 127.0.0.1) and PYTHON_DEBUGPY_PORT (default 5678). --just-my-code scopes probes/exceptions to user code (server-side default true; the CLI flag is a switch — to force false, call via MCP / run execute).
CLI Management Commands
Daemon
ironbee-python-devtools-cli daemon status
ironbee-python-devtools-cli daemon start
ironbee-python-devtools-cli daemon stop
ironbee-python-devtools-cli daemon restart
ironbee-python-devtools-cli daemon info
Session
ironbee-python-devtools-cli session list
ironbee-python-devtools-cli session info <session-id>
ironbee-python-devtools-cli session delete <session-id>
Tools
ironbee-python-devtools-cli tools list
ironbee-python-devtools-cli tools search <query>
ironbee-python-devtools-cli tools info <tool-name>
Config & Updates
ironbee-python-devtools-cli config
ironbee-python-devtools-cli update --check
Python-specific configuration
| Env var | Type | Default | Purpose |
|---|---|---|---|
PYTHON_DEBUGPY_HOST | string | 127.0.0.1 | Default debugpy host for debug connect. |
PYTHON_DEBUGPY_PORT | number | 5678 | Default debugpy port for debug connect. |
PYTHON_INTERPRETER | string | python3 | Interpreter used for debugpy PID/container injection. |
PYTHON_CONSOLE_MESSAGES_BUFFER_SIZE | number | 1000 | Captured stdout/stderr line buffer for debug get-logs. |
PYTHON_HTTP_CAPTURE_BUFFER_SIZE | number | 1000 | Max captured outbound HTTP flows retained (oldest evicted). |
PYTHON_HTTP_CAPTURE_BODY_MAX_BYTES | number | 262144 | Max captured request/response body size in bytes (larger truncated + flagged). |
PYTHON_HTTP_HEADERS_REDACT | string (csv) | authorization,cookie,x-api-key | Header names redacted when --include-headers is set. |
PYTHON_HTTP_BODY_REDACT_KEYS | string (csv) | password,token,secret,… | JSON body keys redacted recursively when --include-bodies is set. |
Examples
Connect and trace a route handler
SESSION="--session-id api-debug"
# Target started with: python -m debugpy --listen 127.0.0.1:5678 app.py
ironbee-python-devtools-cli $SESSION debug connect --host 127.0.0.1 --debugpy-port 5678
# Set tracepoint on the handler
ironbee-python-devtools-cli $SESSION debug put-tracepoint \
--file "routes/users.py" \
--line 25
# Trigger: curl http://localhost:8000/api/users
# Get snapshots
ironbee-python-devtools-cli $SESSION --json debug get-probe-snapshots
PID injection (no restart needed)
ironbee-python-devtools-cli debug connect --pid $(pgrep -f "python app.py")
ironbee-python-devtools-cli debug connect --process-name "app.py"
Exception Catching
SESSION="--session-id exc-debug"
ironbee-python-devtools-cli $SESSION debug connect --host 127.0.0.1 --debugpy-port 5678
ironbee-python-devtools-cli $SESSION debug put-exceptionpoint --state uncaught
# Trigger error in app
ironbee-python-devtools-cli $SESSION --json debug get-probe-snapshots --types exceptionpoint
Thread dump (deadlock / GIL diagnosis)
# Snapshot EVERY thread's stack at once (momentary pause, auto-resume)
ironbee-python-devtools-cli --json debug dump-threads
ironbee-python-devtools-cli --json debug dump-threads --include-locals
Outbound HTTP Capture (egress)
SESSION="--session-id egress-debug"
# Connect, then start capture (first call installs the in-process agent — forward-looking)
ironbee-python-devtools-cli $SESSION debug connect --host 127.0.0.1 --debugpy-port 5678
ironbee-python-devtools-cli $SESSION --json o11y get-http-requests
# Trigger the code path, then read what the process called downstream
ironbee-python-devtools-cli $SESSION --json o11y get-http-requests --url-pattern "*/api/*" --include-headers
# Pin a trace id — the agent injects it as traceparent on every hooked outbound request
ironbee-python-devtools-cli $SESSION --json o11y new-trace-id
Batch with execute
# Run JavaScript in the session VM — python platform only exposes callTool (no `page`)
ironbee-python-devtools-cli run execute --code "await callTool('debug_status', {}, true); await callTool('debug_list-probes', {}, true);"
Interactive Mode
ironbee-python-devtools-cli interactive
| Command | Description |
|---|---|
help | Show commands |
exit, quit | Exit |
debug connect | Connect to process |
debug status | Connection status |
<domain> <tool> | Execute tool |
Shell Completions
eval "$(ironbee-python-devtools-cli completion bash)"
eval "$(ironbee-python-devtools-cli completion zsh)"