Ironbee Terminal Devtools CLI

IronBee Terminal DevTools CLI

Command-line interface for driving interactive terminal programs over a single bridge — a pseudo-terminal (PTY). Part of IronBee DevTools. It spawns a program attached to a PTY and exchanges input/output the way a terminal multiplexer (tmux) does — so programs that behave differently off a TTY (colors, readline, password prompts, ncurses UIs) run the way they would for a human.

Scope: programs the platform spawns itself. It does not attach to a pre-existing external process. Use it for shells, language REPLs (python, node, psql), full-screen TUIs (vim, htop, less), SSH sessions, and any CLI that prompts. For browser UIs use ../ironbee-browser-devtools-cli/SKILL.md; for Node.js process debugging use ../ironbee-node-devtools-cli/SKILL.md; for server APIs use ../ironbee-backend-devtools-cli/SKILL.md.

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

Requires Node.js >= 22.16.0 (engines.node in the package): the backend db domain's SQLite engine and the FTS5 scenario-search strategy run on Node's built-in node:sqlite, which replaced the last native dependency.

Works on macOS, Linux, and Windows (Windows uses ConPTY; POSIX signals are emulated — see pty).

Port note

All IronBee DevTools CLIs default to daemon port 2020. To run the terminal daemon alongside browser (2020), node (2021), backend (2022), and android (2023) daemons, start it on its own port and pass --port to every terminal CLI call:

PLATFORM=terminal ironbee-terminal-devtools-cli daemon start --port 2024
ironbee-terminal-devtools-cli --port 2024 pty list

Quick Start

# 1. Start daemon (if not running)
ironbee-terminal-devtools-cli daemon start

# 2. Spawn a shell pane, capture the paneId
ironbee-terminal-devtools-cli --session-id work --json pty start

# 3. Type a command and run it
ironbee-terminal-devtools-cli --session-id work interaction send-keys --pane-id <id> --keys '["ls -la","Enter"]'

# 4. Block until the prompt returns, then read what was emitted
ironbee-terminal-devtools-cli --session-id work --json sync wait-for --pane-id <id> --pattern '\$ $'
ironbee-terminal-devtools-cli --session-id work --json content capture --pane-id <id>

# 5. Stop the pane when done
ironbee-terminal-devtools-cli --session-id work pty stop --pane-id <id>

For a non-interactive command, skip the pane lifecycle entirely:

ironbee-terminal-devtools-cli --json pty run --command "npm test"

Global Options

AI Agent Recommended:

ironbee-terminal-devtools-cli --json --quiet --session-id "terminal-session" <command>

Model (panes)

A pane is one PTY-backed process. pty start spawns a shell (or a specific program) and returns a paneId; many panes can run concurrently in a session. Panes are addressed by --pane-id on every interaction / content / sync / signal / resize call. Exited panes are retained — with their final output still readable via content capture — until pty stop forgets them.

Synchronization model (wait, don't sleep)

There is no assert tool and no fixed-delay step. Send input, then block on expected output with sync wait-for (regex match) or sync wait-for-idle (output went quiet) before sending the next input or reading. Use the returned cursor to chain incremental reads — pass it as --since to the next content capture / sync wait-for so you only see new output. This is the right way to drive a prompt-driven program; guessing with delays is unreliable.

Capture modes

• stream (default): the raw scrollback as the program emitted it — best for line-oriented programs (REPLs, shells, git/npm output). Supports incremental reads via --since.
• screen: the current rendered terminal grid (what a user would see now) — best for full-screen TUIs (vim, htop, less) where cursor positioning matters.

Tool Domains

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-terminal-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.

Full scenario surface on this CLI. The terminal CLI registers the scenario CRUD subcommands (scenario-add / scenario-update / scenario-delete / scenario-list / scenario-search / scenario-recorded-actions) plus a direct scenario-run subcommand under the default group — e.g. ironbee-terminal-devtools-cli default scenario-run --name <name> (with --args / --param key=value / --timeout-ms, and --resume / --step-by-step / --refresh for step-based scenarios). scenario-run is also reachable from inside run execute via await callTool('scenario-run', { name: '...' }). See the scenario reference. Inside a scenario script only callTool is available (no page binding — that is browser-only).

Secret redaction

Terminal output can echo secrets (export TOKEN=..., tokens pasted at prompts). Returned content from content capture, sync wait-for, and pty run is scrubbed of well-known secret shapes (Bearer / Basic / header / KV / env-secret) before it reaches the model, and the same scrubbing covers tool input/output on collector events. Master toggle: TERMINAL_REDACT_ENABLE (default true).

CLI Management Commands

Daemon

ironbee-terminal-devtools-cli daemon status
ironbee-terminal-devtools-cli daemon start
ironbee-terminal-devtools-cli daemon stop
ironbee-terminal-devtools-cli daemon restart
ironbee-terminal-devtools-cli daemon info

Session

ironbee-terminal-devtools-cli session list
ironbee-terminal-devtools-cli session info <session-id>
ironbee-terminal-devtools-cli session delete <session-id>

Tools

ironbee-terminal-devtools-cli tools list
ironbee-terminal-devtools-cli tools search <query>
ironbee-terminal-devtools-cli tools info <tool-name>

Config

ironbee-terminal-devtools-cli config

Terminal-specific configuration

The default shell comes from $SHELL (POSIX) or %COMSPEC% / PowerShell (Windows); override per-pane with pty start --command.

Examples

Drive a Python REPL

SESSION="--session-id repl"

# Spawn python directly as the pane process
PANE=$(ironbee-terminal-devtools-cli $SESSION --json pty start --command python | jq -r '.paneId')

# Wait for the >>> banner, then send an expression
ironbee-terminal-devtools-cli $SESSION --json sync wait-for --pane-id "$PANE" --pattern '>>> '
ironbee-terminal-devtools-cli $SESSION interaction send-keys --pane-id "$PANE" --keys '["2 + 40","Enter"]'

# Block until the next prompt, then read only the new output
ironbee-terminal-devtools-cli $SESSION --json sync wait-for --pane-id "$PANE" --pattern '>>> '
ironbee-terminal-devtools-cli $SESSION --json content capture --pane-id "$PANE" --strip-ansi

ironbee-terminal-devtools-cli $SESSION pty stop --pane-id "$PANE"

Inspect a full-screen TUI

SESSION="--session-id tui"
PANE=$(ironbee-terminal-devtools-cli $SESSION --json pty start --command vim --cols 120 --rows 40 | jq -r '.paneId')

# Read the rendered grid (not raw stream) for a TUI
ironbee-terminal-devtools-cli $SESSION --json content capture --pane-id "$PANE" --mode screen

# Type ':q!' then Enter to quit
ironbee-terminal-devtools-cli $SESSION interaction send-keys --pane-id "$PANE" --keys '[":q!","Enter"]'

One-shot command with exit code

# pipes / && / redirection work because the command runs through a shell
ironbee-terminal-devtools-cli --json pty run --command "grep -r TODO src | wc -l"

Interrupt a long-running process

# Send the Ctrl-C keystroke (the program may trap it) ...
ironbee-terminal-devtools-cli interaction send-keys --pane-id <id> --keys '["C-c"]'
# ... or deliver a real process signal (kept pane)
ironbee-terminal-devtools-cli pty signal --pane-id <id> --signal SIGINT

Batch with execute

# Run multiple tool calls in one request — terminal exposes only callTool (no `page`)
ironbee-terminal-devtools-cli run execute --code "const p = await callTool('pty_start', {}, true); await callTool('interaction_send-keys', { paneId: p.paneId, keys: ['echo hi','Enter'] });"

Interactive Mode

ironbee-terminal-devtools-cli interactive

Shell Completions

eval "$(ironbee-terminal-devtools-cli completion bash)"
eval "$(ironbee-terminal-devtools-cli completion zsh)"