CLI, Debugger & Web Inspector Reference

This page documents all command-line subcommands, flags, environment variables, the interactive REPL, the terminal debugger (tdb), and the live browser-based Web Inspector IDE.

1. CLI Command Synopsis

tinsel [command] [flags...] [arguments...]

2. Running, Checking & Testing Scripts

Single-File & Batch Execution (run)

• Single Script with CLI Arguments: Arguments after <file.tin> populate the global args: [string] array:
  bash

  Copy

  ./bin/tinsel run examples/aoc2025/day01.tin inputs/day01.txt
  

• Directory & Multi-File Batch Execution: Pass a directory or shell glob to run multiple scripts sequentially:
  bash

  Copy

  ./bin/tinsel examples/aoc2025/
  ./bin/tinsel examples/aoc2023_*.tin
  

Static Verification (check) & Test Suites (test)

• tinsel check validates syntax, variable mutability (let vs. let mut), and pattern compilation across files or directories without executing code:
  bash

  Copy

  ./bin/tinsel check examples/ tests/ stdlib/
  

• tinsel test runs all test scripts in tests/ (or specified paths) and reports timing per file:
  bash

  Copy

  ./bin/tinsel test
  ./bin/tinsel test tests/test_struct.tin
  

Code Coverage Analysis (--cover)

Both tinsel run and tinsel test support line, function/method, and branch (if/else and match arm) coverage tracking across user scripts, imported local .tin modules, and optionally embedded std/* modules:

# Run test suite with per-function summary and standalone HTML report
./bin/tinsel test --cover --cover-func --cover-html=coverage.html

# Run a single script with annotated terminal source and LCOV export
./bin/tinsel run --cover-show --cover-out=coverage.info examples/aoc2025/day01.tin

Bytecode Disassembly (compile) & Web Playground (play)

Inspect the compiler's optimized bytecode (including constant folding and superinstructions) or pass --no-opt (-O0) to view unoptimized 1-to-1 bytecode:

./bin/tinsel compile examples/aoc2023_day1.tin
./bin/tinsel compile --no-opt examples/aoc2023_day1.tin

Launch the interactive Tinsel Playground server to edit and execute code in your browser, test custom puzzle inputs (input.txt), browse bundled examples, compare -O vs -O0 bytecode side by side, and run code blocks inline across the HTML documentation:

./bin/tinsel play
./bin/tinsel play -p 9000

Environment Variables & Exit Codes

• TINSEL_PATH: Colon-separated list of directories (semicolon-separated on Windows) searched when resolving module imports.
• TINSEL_DEBUG_ADDR: Default host:port (e.g. 127.0.0.1:4040) for the Web Debugger; when set during tinsel run, automatically attaches the live debug endpoint.
• TINSEL_PLAY_ADDR: Default host:port (e.g. 127.0.0.1:8080) for tinsel play.
• Exit Codes: 0 on success; 1 on syntax, compilation, runtime, or assertion error.

3. Live Web Inspector IDE & Debugger (tinsel debug)

Tinsel embeds a zero-dependency source-level and bytecode-level debugger with both a browser-based Web Inspector IDE and an interactive terminal CLI (tdb).

+-------------------------------+                  +-------------------------------+
|     Web Browser Inspector     |  SSE /api/events |     Embedded Debug Server     |
|    (http://127.0.0.1:4040)    | <--------------> |      (internal/debugger)      |
+-------------------------------+  REST /api/eval  +-------------------------------+
                                                              ^         ^
+-------------------------------+                             |         | DebugHook &
|    Terminal CLI Debugger      | ----------------------------+         | EvalInFrame
|   (tinsel debug --cli / tdb)  |                                       v
+-------------------------------+                  +-------------------------------+
                                                   |      Tinsel Bytecode VM       |
                                                   |         (internal/vm)         |
                                                   +-------------------------------+

Launching the Debugger

1. Dedicated Debug Session (Paused on Line 1):
   bash

   Copy

   ./bin/tinsel debug examples/aoc2024_day16.tin
   # Custom port or start running immediately until a breakpoint/dbg() is hit:
   ./bin/tinsel debug -p 8080 --run examples/aoc2024_day16.tin
   

2. Attaching to a Normal tinsel run Job:
   bash

   Copy

   ./bin/tinsel run --debug examples/aoc2024_day16.tin
   ./bin/tinsel run --debug-brk=127.0.0.1:4040 examples/aoc2024_day16.tin
   

Programmatic Breakpoints (dbg & breakpoint)

Call dbg(expr) or breakpoint() anywhere in your .tin code to pause when the debugger is attached. When running normally without a debugger, dbg(x) is a fast no-op that returns x unchanged:

let total = dbg([10, 20, 30].sum())
assert(total == 60)

Web Inspector IDE Features

• Stepping Controls: Continue (F8), Step Over (F10), Step Into (F11), Step Out (Shift+F11), Step Single Bytecode Instruction, Live Pause, and Restart.
• Conditional Breakpoints: Click any line number in the gutter to toggle a breakpoint, or Shift+Click to attach a Tinsel condition expression (e.g. cost > 500 && pos == vec2(5, 5)).
• 2D Grid & RangeSet Visualizers: Automatically renders grid variables as color-coded 2D boards and rangeset variables as interval badges.
• Live Code Coverage Overlay (📊 Cov): Highlights executed (green), partial-branch (amber), and unexecuted (red) source lines in real time with execution hit counts (14x) in the gutter and a dedicated Coverage tab showing per-function call counts and line percentages.
• Live Frame Evaluator: Evaluate arbitrary Tinsel expressions in the lexical scope of any paused call frame.

4. Terminal CLI Debugger (tdb)

Pass --cli to debug directly in your terminal (./bin/tinsel debug --cli <file.tin>):

5. Debugger HTTP REST & SSE API

External tools can integrate with the embedded debug server (internal/debugger/server.go):