Skip to content

metta-debug-cli.md

Latest commit

 

History

History
266 lines (189 loc) · 8.08 KB

metta-debug-cli.md

File metadata and controls

266 lines (189 loc) · 8.08 KB
Raw

MeTTa TUI Debugger CLI

metta-debug-cli is the non-TUI command surface for MeTTa TUI Debugger. It uses the same Hyperon-backed debugger engine as the TUI, but runs one batch command and prints a human-readable summary by default.

Use it when you want shell automation, smoke tests, scripted inspection, or a quick debugger snapshot without opening the terminal UI.

Quick Start

Run commands from the repository or bundle root.

Evaluate inline executable source:

./bin/metta-debug-cli --source '!(+ 1 2)' run

Expected human result shape:

Status: Completed
Result: 3
Total steps: 111
Elapsed: 0.001s

For structured output, pass --llm:

./bin/metta-debug-cli --llm --source '!(+ 1 2)' run

Step once and return the paused debugger snapshot:

./bin/metta-debug-cli --source '!(+ 1 2)' step --count 1

Debug a file:

./bin/metta-debug-cli --file path/to/program.metta run
./bin/metta-debug-cli --file path/to/program.metta step --count 5

List the full debugger protocol:

./bin/metta-debug-cli protocol-help

Run the built-in debugger smoke suite:

./bin/metta-debug-cli self-test
./bin/metta-debug-cli --llm self-test

Mental Model

Each invocation creates a fresh debugger session:

  1. Initialize the debugger runtime.
  2. Optionally load --source or --file.
  3. Run one CLI subcommand.
  4. Print human-readable text by default, or JSON in --llm mode.
  5. Exit.

State does not persist between invocations. Breakpoints, watches, loaded source, and selected branches must be recreated in the same invocation, usually through the rpc escape hatch if there is no dedicated CLI shortcut.

Executable MeTTa expressions use !. Non-! atoms are loaded as definitions and do not create an expression to step or run by themselves.

Global Options

These options can be used with every subcommand:

--file PATH                         Load a .metta file.
--source SOURCE                     Load inline MeTTa source.
--working-dir DIR                   Working directory for module resolution.
--include PATH                      Add an include path. Repeat as needed.
--max-steps N                       Maximum reduction steps. Default: 100000.
--max-stack-depth N                 Evaluation stack depth. Default: 2048.
--step-timeout-ms N                 Per-step timeout. Default: 5000.
--collect-trace                     Ask the debugger to record protocol trace entries.
--reduction-trace-max-entries N     Retain more reduction trace entries.
--stop-on-entry                     Pause immediately after load.
--with-events                       Include emitted debugger events.
--human                            Print human-readable output. Default.
--llm                              Print structured pretty JSON.
--compact-json                     Print one-line JSON. Implies --llm.

Use default human mode for terminal reading. Use --llm when an agent or model needs the full structured payload. Prefer --compact-json for scripts and jq pipelines.

Common Workflows

Test The Debugger Surface

./bin/metta-debug-cli self-test
./bin/metta-debug-cli --llm self-test

self-test uses a built-in source program and verifies initialization, load, state, step, run-to-completion, evaluation, space inspection, metrics, watches, session info, panel reads, trace reads, breakpoints, and protocol help. It is the fastest check when you need to confirm the non-TUI debugger surface works.

For the full MeTTa TUI Debugger bundle, run:

./test-everything.sh

That script also covers formatting, Rust tests, clippy, release binaries, JSON-RPC server framing, TUI tape replay, and a PTY fast-input stress run.

Run To Completion

./bin/metta-debug-cli --source '!(+ 1 2)' run
./bin/metta-debug-cli --llm --source '!(+ 1 2)' run
./bin/metta-debug-cli --file path/to/program.metta run --compact-json

run loads source paused, then sends the debugger runToCompletion command. Breakpoints are ignored by the protocol command it uses.

Step Through Source

./bin/metta-debug-cli --source '!(+ 1 2)' step --count 1
./bin/metta-debug-cli --file path/to/program.metta step --count 10 --with-events

step, step-over, step-out, and continue require --file or --source. The CLI loads source paused for these execution commands so the first step is observable.

Evaluate An Expression

./bin/metta-debug-cli eval '(+ 2 3)' --full-reduce
./bin/metta-debug-cli --file defs.metta eval '(double 21)' --full-reduce

Use eval for direct expression evaluation in the initialized runtime. Add --file or --source first when the expression depends on definitions.

Inspect The Space

./bin/metta-debug-cli --file defs.metta inspect-space --limit 25
./bin/metta-debug-cli --file defs.metta inspect-space --pattern double --limit 10
./bin/metta-debug-cli --file defs.metta inspect-space --query-pattern '(= (double $x) $body)'

Use inspect-space to look at loaded definitions and runtime space atoms. Add --llm or --compact-json when the output needs to be filtered with jq.

Observe Steps And Trace Buffers

For visible step-by-step state, prefer step --with-events:

./bin/metta-debug-cli --source '!(+ 1 2)' step --count 1 --with-events

The protocol trace buffer is also exposed:

./bin/metta-debug-cli --collect-trace --source '!(+ 1 2)' trace --max-entries 20

The reduction trace buffer is exposed separately:

./bin/metta-debug-cli --source '!(+ 1 2)' reduction-trace --max-entries 20

These trace-buffer commands can return empty arrays for simple run cases in this build. Use step --with-events when you need a reliable observable execution snapshot.

Read Debugger Panels

./bin/metta-debug-cli --file path/to/program.metta read-panel source --limit 50
./bin/metta-debug-cli --file path/to/program.metta read-panel space --offset 50 --limit 50

Panels are useful when a full state snapshot is too large.

Use Raw Protocol Commands

The rpc subcommand accepts debugger protocol JSON. Use it for protocol features without a dedicated CLI shortcut.

./bin/metta-debug-cli --source '!(+ 1 2)' rpc '{"command":"getState"}'
./bin/metta-debug-cli --source '!(+ 1 2)' rpc '{"command":"listBreakpoints"}'
./bin/metta-debug-cli --file defs.metta rpc '{"command":"inspectSpace","params":{"limit":10}}'

A full request object with an id is also accepted; the CLI extracts the command and assigns its own internal request id.

Relationship To Other Binaries

./bin/metta-debug-cli : Human and script-friendly batch CLI. Use this for non-TUI work.

./bin/metta-debugger : JSON-RPC and DAP server binary. The TUI launches this over stdin/stdout. It is not the human CLI.

./bin/metta-tui : Ratatui terminal UI debugger.

./run-tui.sh : Wrapper that points the TUI at the bundled metta-debugger binary.

Build From Source

The bundle includes stripped binaries in bin/. To rebuild from source:

cargo build -p metta-tui --bin metta-debug-cli --offline
./target/debug/metta-debug-cli --source '!(+ 1 2)' run --compact-json

To rebuild both debugger entry points and the TUI:

cargo build -p metta-tui --bins --offline

Troubleshooting

pass --file PATH or --source SOURCE for this command : The selected command needs source loaded first. Add --file or --source.

InvalidState or a loaded-runtime error : The raw rpc command likely needs initialization or loaded source. Do not use rpc --no-init unless you are intentionally testing protocol errors.

Trace output is empty : Add --collect-trace before the trace subcommand. If it is still empty, use step --with-events for observable debugger state.

Output is too large : Query a smaller surface with read-panel, inspect-space --limit, trace --max-entries, or reduction-trace --max-entries. For structured post-processing, use --llm or --compact-json and pipe through jq.

Shell quoting breaks inline source : Wrap inline MeTTa in single quotes, especially when it contains ! or $. For longer programs, write a .metta file and pass --file.