CLI Command Reference

The CLI is an alternative interface to the same tooling that agents access via MCP. Every debug_* and chrome_* MCP tool has a corresponding CLI command. Many agent setups prefer CLI tools for their transparency, composability, and ease of scripting. The CLI is also useful for CI pipelines and convenience operations like doctor.

All commands output the viewport to stdout as structured plain text. Exit codes: 0 for success, 1 for errors, 2 for timeouts.

Command Structure

The CLI uses namespaced subcommands:

krometrail debug <command>     # Debug session commands
krometrail chrome <command>   # Browser recording commands
krometrail doctor              # Check installed debuggers
krometrail commands            # List all commands (machine-readable)
krometrail completions <shell> # Generate shell completions (bash, zsh, fish)

Global Flags

These flags are available on all debug and browser commands:

Flag	Description
`--session <id>`, `-s`	Target a specific debug session (required when multiple sessions are active)
`--json`	Output structured JSON instead of plain text
`--quiet`	Suppress banners and hints; output viewport only
`--version`	Show version

Session Lifecycle

`debug launch`

bash

krometrail debug launch "python app.py" --break order.py:147
krometrail debug launch "python -m pytest tests/ -x" --break "order.py:147 when discount < 0"
krometrail debug launch "node index.js" --break src/api.js:30 --language javascript
krometrail debug launch "go test ./..." --break service/order.go:147

Flag	Type	Required	Description
`<command>`	positional	No	Command to debug, e.g. 'python app.py' or 'pytest tests/'
`--break`, `-b`	string	No	Set breakpoint(s), e.g. 'order.py:147' or 'order.py:147 when discount < 0'
`--language`	string	No	Override language detection. Supported: python, node/javascript/typescript/js/ts, go, rust, java, cpp, ruby, csharp, swift, kotlin
`--framework`	string	No	Override framework auto-detection. Known: pytest, django, flask, jest, mocha, gotest, pytest, django, flask, jest, mocha, gotest. Use 'none' to disable.
`--stop-on-entry`	boolean	No	Pause on first executable line
`--config`	string	No	Path to launch.json file (default: .vscode/launch.json)
`--config-name`, `-C`	string	No	Name of the configuration to use from launch.json
`--cwd`	string	No	Working directory for the debug target
`--env`	string	No	Environment variables as KEY=VAL pairs (comma-separated, e.g. DEBUG=1,LOG=verbose)
`--source-lines`	string	No	Lines of source context above/below current line (default: 15)
`--stack-depth`	string	No	Max call stack frames to show (default: 5)
`--locals-depth`	string	No	Object expansion depth for locals (default: 1)
`--token-budget`	string	No	Approximate token budget for viewport output (default: 8000)
`--diff-mode`	boolean	No	Show only changed variables vs previous stop

`debug attach`

bash

krometrail debug attach --port 5678 --language python
krometrail debug attach --pid 12345 --language go

Flag	Type	Required	Description
`--language`	string	Yes	Language. Supported: python, node/javascript/typescript/js/ts, go, rust, java, cpp, ruby, csharp, swift, kotlin
`--pid`	string	No	Process ID
`--port`	string	No	Debug server port
`--host`	string	No	Debug server host
`--break`, `-b`	string	No	Set breakpoint(s), e.g. 'app.py:10'
`--cwd`	string	No	Working directory for the debug target
`--source-lines`	string	No	Lines of source context above/below current line (default: 15)
`--stack-depth`	string	No	Max call stack frames to show (default: 5)
`--locals-depth`	string	No	Object expansion depth for locals (default: 1)
`--token-budget`	string	No	Approximate token budget for viewport output (default: 8000)
`--diff-mode`	boolean	No	Show only changed variables vs previous stop

`debug status`

bash

krometrail debug status

`debug stop`

bash

krometrail debug stop
krometrail debug stop --session abc123

Execution Control

`debug continue`

bash

krometrail debug continue
krometrail debug continue --timeout 10000

Flag	Type	Required	Description
`--timeout`	string	No	Max wait time in ms
`--thread`	string	No	Thread ID to continue (for multi-threaded debugging)

`debug step`

bash

krometrail debug step over
krometrail debug step into
krometrail debug step out
krometrail debug step over --count 5

Flag	Type	Required	Description
`<direction>`	positional	Yes	Step direction: over, into, or out
`--count`	string	No	Number of steps
`--thread`	string	No	Thread ID to step (for multi-threaded debugging)

`debug run-to`

bash

krometrail debug run-to order.py:155

Flag	Type	Required	Description
`<location>`	positional	Yes	Target location, e.g. 'order.py:150'
`--timeout`	string	No	Max wait time in ms

Breakpoints

`debug break`

bash

# Set breakpoints (replaces existing in that file)
krometrail debug break order.py:147
krometrail debug break order.py:147,150,155

# Conditional
krometrail debug break "order.py:147 when discount < 0"

# Hit count
krometrail debug break "order.py:147 hit >=100"

# Logpoint
krometrail debug break "order.py:147 log 'discount={discount}'"

# Exception breakpoints
krometrail debug break --exceptions uncaught
krometrail debug break --exceptions raised
krometrail debug break --exceptions all

# Clear all breakpoints in a file
krometrail debug break --clear order.py

Flag	Type	Required	Description
`--breakpoint`	string	No	Breakpoint spec: 'file:line[,line] [when cond] [hit cond] [log msg]'
`--exceptions`	string	No	Set exception breakpoint filter (e.g. 'uncaught', 'raised')
`--clear`	string	No	Clear all breakpoints in a file

`debug breakpoints`

bash

krometrail debug breakpoints

State Inspection

`debug eval`

bash

krometrail debug eval "<expression>"
krometrail debug eval "cart.items[0].__dict__" --depth 3
krometrail debug eval "request.headers" --frame 2

Flag	Type	Required	Description
`<expression>`	positional	Yes	Expression to evaluate, e.g. 'cart.items[0].dict'
`--frame`	string	No	Stack frame index (0 = current)
`--depth`	string	No	Object expansion depth

`debug vars`

bash

krometrail debug vars
krometrail debug vars --scope global
krometrail debug vars --scope closure
krometrail debug vars --scope all
krometrail debug vars --filter "^user"
krometrail debug vars --frame 2

Flag	Type	Required	Description
`--scope`	string	No	Variable scope: local, global, closure, or all
`--filter`	string	No	Regex filter on variable names
`--frame`	string	No	Stack frame index (0 = current)

`debug stack`

bash

krometrail debug stack
krometrail debug stack --frames 20
krometrail debug stack --source

Flag	Type	Required	Description
`--frames`	string	No	Maximum frames to show
`--source`	boolean	No	Include source context per frame

`debug source`

bash

krometrail debug source order.py
krometrail debug source order.py:140-160

Flag	Type	Required	Description
`<target>`	positional	Yes	File path, optionally with line range: 'file.py:15-30'

Session Intelligence

`debug watch`

bash

krometrail debug watch "len(cart.items)" "user.tier" "total > 0"

Flag	Type	Required	Description
`<expressions>`	positional	Yes	Expression(s) to watch

`debug unwatch`

bash

krometrail debug unwatch "user.tier"

Flag	Type	Required	Description
`<expressions>`	positional	Yes	Expression(s) to stop watching

`debug log`

bash

krometrail debug log
krometrail debug log --detailed

Flag	Type	Required	Description
`--detailed`	boolean	No	Show detailed log with timestamps

`debug output`

bash

krometrail debug output
krometrail debug output --stderr
krometrail debug output --since-action 5

Flag	Type	Required	Description
`--stderr`	boolean	No	Show only stderr
`--stdout`	boolean	No	Show only stdout
`--since-action`	string	No	Only show output since action N

`debug threads`

bash

krometrail debug threads

Browser Recording

`browser start`

bash

krometrail chrome start --url http://localhost:3000
krometrail chrome start --url http://localhost:3000 --framework-state auto
krometrail chrome start --url http://localhost:3000 --framework-state react
krometrail chrome start --attach                    # Attach to already-running Chrome
krometrail chrome start --profile myproject          # Use isolated Chrome profile
krometrail chrome start --all-tabs                   # Record all tabs

`browser status`

bash

krometrail chrome status

`browser mark`

bash

krometrail chrome mark "user submitted form"

`browser stop`

bash

krometrail chrome stop
krometrail chrome stop --close-browser

`browser export`

bash

krometrail chrome export <session-id> --format har --output file.har

Browser Session Investigation

`browser sessions`

bash

krometrail chrome sessions
krometrail chrome sessions --has-errors
krometrail chrome sessions --url-contains "localhost:3000"

`browser overview`

bash

krometrail chrome overview <session-id>
krometrail chrome overview <session-id> --around-marker <marker-id>
krometrail chrome overview <session-id> --include timeline,markers,errors

`browser search`

bash

krometrail chrome search <session-id> --query "payment failed"
krometrail chrome search <session-id> --event-types network_response --status-codes 500
krometrail chrome search <session-id> --framework react --pattern stale_closure

`browser inspect`

bash

krometrail chrome inspect <session-id> --event <event-id>
krometrail chrome inspect <session-id> --marker <marker-id>
krometrail chrome inspect <session-id> --timestamp "2025-01-15T10:30:00Z"

`browser diff`

bash

krometrail chrome diff <session-id> --from <timestamp-or-event-id> --to <timestamp-or-event-id>

`browser replay-context`

bash

krometrail chrome replay-context <session-id>
krometrail chrome replay-context <session-id> --format test_scaffold --framework playwright
krometrail chrome replay-context <session-id> --format test_scaffold --framework cypress

Utility

`doctor`

bash

krometrail doctor
krometrail doctor --json

`commands`

bash

krometrail commands
krometrail commands --group debug
krometrail commands --group browser

Flag	Type	Required	Description
`--group`	string	No	Filter by command group: debug, chrome, or all

`completions`

bash

krometrail completions bash
krometrail completions zsh
krometrail completions fish

See Shell Completions below for installation instructions.

Shell Completions

Generate shell completion scripts for tab-completion of commands, subcommands, and flags:

bash

# Bash
krometrail completions bash > ~/.local/share/bash-completion/completions/krometrail
# Or add to ~/.bashrc:
source <(krometrail completions bash)

# Zsh
krometrail completions zsh > "${fpath[1]}/_krometrail"
# Or add to ~/.zshrc:
source <(krometrail completions zsh)

# Fish
krometrail completions fish > ~/.config/fish/completions/krometrail.fish

JSON Output

Every command supports --json for structured output:

bash

krometrail debug continue --json

json

{
	"status": "stopped",
	"reason": "breakpoint",
	"location": { "file": "order.py", "line": 147, "function": "process_order" },
	"stack": [...],
	"locals": { "discount": { "type": "float", "value": "-149.97" }, ... },
	"source": { "file": "order.py", "start_line": 140, "lines": [...] }
}

CLI Command Reference ​

Command Structure ​

Global Flags ​

Session Lifecycle ​

debug launch ​

debug attach ​

debug status ​

debug stop ​

Execution Control ​

debug continue ​

debug step ​

debug run-to ​

Breakpoints ​

debug break ​

debug breakpoints ​

State Inspection ​

debug eval ​

debug vars ​

debug stack ​

debug source ​

Session Intelligence ​

debug watch ​

debug unwatch ​

debug log ​

debug output ​

debug threads ​

Browser Recording ​

browser start ​

browser status ​

browser mark ​

browser stop ​

browser export ​

Browser Session Investigation ​

browser sessions ​

browser overview ​

browser search ​

browser inspect ​

browser diff ​

browser replay-context ​

Utility ​

doctor ​

commands ​

completions ​

Shell Completions ​

JSON Output ​

CLI Command Reference

Command Structure

Global Flags

Session Lifecycle

`debug launch`

`debug attach`

`debug status`

`debug stop`

Execution Control

`debug continue`

`debug step`

`debug run-to`

Breakpoints

`debug break`

`debug breakpoints`

State Inspection

`debug eval`

`debug vars`

`debug stack`

`debug source`

Session Intelligence

`debug watch`

`debug unwatch`

`debug log`

`debug output`

`debug threads`

Browser Recording

`browser start`

`browser status`

`browser mark`

`browser stop`

`browser export`

Browser Session Investigation

`browser sessions`

`browser overview`

`browser search`

`browser inspect`

`browser diff`

`browser replay-context`

Utility

`doctor`

`commands`

`completions`

Shell Completions

JSON Output