Interactive CLI

6 min read

The CLI is the main way you use tsforge. REPL mode means an interactive session: you type tasks, steer with slash commands, and the harness keeps context between turns.

Most users run tsforge and stay in the interactive session.

Note: See Input Editor for keyboard shortcuts, multi-line paste, and history navigation.

Modes

Mode	How	When
Interactive	`tsforge`	default: open-ended tasks, steering, exploration
One-shot	`tsforge "task" --accept "gate cmd"`	drive a single task to green and exit
New app	`tsforge scaffold`	stand up BoringStack, its Astro site, or a Phaser game, then build with the greenfield loop
Plan mode	default: Shift+Tab or `/plan` to switch	read-only explore → approve saves a project checklist → implement in-session. See Plan mode.

Flags

Flag	Effect
`--dir <path>`	target project (default: cwd)
`--files <globs>`	narrow editable scope (comma-separated); default is whole repo (vendored/generated files are always excluded)
`--accept` / `--gate <cmd>`	gate command for one-shot mode
`--no-gate`	skip auto gate detection
`--browser <html>`	append headless render check to gate
`--plan`	force plan mode on for an interactive session. Plan is the default anyway, so this only matters to override a repo that configured an autonomous `policy.mode`; ignored by one-shot/headless
`--continue` / `-c`	resume latest saved session for this dir (restores `activePlanId`; Tasks rail reloads that plan)
`--resume <id>`	resume a specific session
`--log`	append JSONL event stream to `~/.tsforge/logs/`

Model endpoint overrides: TSFORGE_BASE_URL, TSFORGE_MODEL. See Environment variables.

Slash commands

Command	Action
`/help`	list commands
`/scaffold`	create a new project here (BoringStack / Astro / Phaser) via the wizard
`/plan`	toggle plan mode (on by default; approve saves the checklist and implements)
`/config`	settings hub: model (switch/add), mode, gate, editable scope, and tools (web, TDD); each with a description + live value
`/gate <cmd>`	set gate command (`/gate` alone clears)
`/files <globs>`	set editable scope
`/review [base]`	review your current change (logic, regressions, edge cases)
`/map [status\|forget]`	build a structural map of the repo to prime the agent
`/trace [logfile]`	summarize a `--log` run (calls, policy decisions, gate verdicts, turns-to-green)
`/setup`	infer + write project conventions (the setup wizard)
`/model [name]`	list models or switch active model
`/sessions`	list saved sessions
`/compact`	summarize conversation to free context
`/clear`	reset conversation (keeps workspace + gate)
`/cost`	rough token estimate
`/metrics`	token totals + generation rate (tok/s) this session
`/memory`	show coding lessons + project decisions (`/memory forget` clears them)
`/exit`	quit (`/quit` is an alias)

Anything else is sent to the agent. While it runs, type to steer the next turn. Ctrl-C interrupts the current run.

Shift+Tab cycles the interactive mode (plan → normal → …); the current mode shows as a ◆ chip in the status bar.

Right rail (Tasks / Gate)

On a tall enough terminal, tsforge opens a two-column pane console: transcript on the left, a right rail on the right. Default keybindings (all remappable — see below):

Action	Default chord
Toggle rail	`ctrl+g`
Cycle Tasks ↔ Gate	`f6` (also `ctrl+shift+g` when your terminal sends modifyOtherKeys)
Focus rail / return to prompt	`Tab` / `Esc`
Move selection	`↑`/`↓` or `k`/`j` (when rail focused)
Keymap overlay	`?` (idle, empty prompt)

Tasks shows the session checklist (plan items, verify hints, focused-task spinner while the agent runs). Gate lists structured gate errors from the last settle — rule, file:line, and a one-line rule doc for the selected row. Press Enter on a focused gate row to insert steer text (fix <rule> at <file>:line) into the prompt.

File:line segments in the gate rail (and matching tool output lines) render as OSC 8 hyperlinks in supporting terminals. Disable with TSFORGE_NO_OSC8=1.

Press ? when idle to see your effective bindings (including overrides from config).

Remapping pane keys

Logical chords live in config — never raw terminal bytes. User-global ~/.tsforge/config.json wins over project tsforge.config.json:

{
  "tui": {
    "keybindings": {
      "pane.toggle": "ctrl+\\",
      "pane.cycleSurface": "f6",
      "keymap.show": "?"
    }
  }
}

Supported modifiers: ctrl, shift, alt, meta. Keys: letters, ?, \, tab, escape, enter, up, down, f6, … See Configuration.

Status bar

On a real terminal, a status bar stays pinned to the bottom while output scrolls above it, always in view and never scrolled away:

  ⎯ deepseek-v4-flash · ◆ plan · ctx ~8k/32k 25% · 2 turns · 12s · 48 tok/s · done · src/**

It shows the active model, the current mode chip (◆ plan / ◆ normal), real context-window usage, the last turn’s count + elapsed, the current generation rate, the last outcome, and the editable scope. It ticks live while the model works: tokens/sec and the context meter update mid-turn (the status reads ● working), settling to ✓ done / ✗ stuck when the turn ends, and it survives terminal resizes. When stdout isn’t a TTY (piped output, --log, a tiny window) the bar is skipped and the same line prints inline above each prompt instead, so logs and pipes stay clean.

Live metrics

The status bar shows the last call’s generation rate (tok/s) next to the context gauge. /metrics prints the running totals for the session: model calls, input/output tokens, and both the last and average output rate:

  4 call(s) · 8120 in / 1540 out · 47 tok/s last · 44 tok/s avg

tokens/sec measures output generation (from the first streamed token to the call’s end), so it reflects decode speed rather than prompt-processing latency. Per-call usage is also written to the --log JSONL for post-hoc analysis.

Full guide, including log analysis: Token metrics & tokens/sec.

On start you see:

cwd: target project
scope: editable file globs
gate: acceptance command (auto-detected or set)
model: active entry from ~/.tsforge/models.json
session: new or resumed id

Gate auto-detection is described in How the gate is built.

Model registry

Models live in ~/.tsforge/models.json. Use /model to hot-swap without restarting. See Quickstart for a starter config.

Run logs

--log writes every loop event (tool calls, gate verdicts, repairs) as JSONL under ~/.tsforge/logs/. Use this for eval analysis. See A/B testing.

→ Quickstart · Plan mode · Model adapter