CLI Reference

The namu CLI communicates with the running app over a Unix domain socket using JSON-RPC 2.0. The default socket path is /tmp/namu.sock. Tagged debug builds use /tmp/namu-<tag>.sock.

Usage

namu <namespace> <command> [--param value ...]

Global Flags

Ref IDs

All commands accept short ref IDs in kind:ordinal format as well as full UUIDs. Refs are stable within a session:

workspace:1   pane:2   surface:3

Use --id-format both to see refs and UUIDs side by side in list output.

workspace.*

namu workspace list
namu workspace create --title "Backend"
namu workspace select --id workspace:1
namu workspace rename --id workspace:1 --title "Frontend"
namu workspace pin --id workspace:1
namu workspace color --id workspace:1 --color "#FF6B6B"
namu workspace delete --id workspace:1

pane.*

namu pane split --direction horizontal
namu pane split --direction vertical --pane_id pane:2
namu pane focus --pane_id pane:1
namu pane resize --split_id pane:2 --ratio 0.6
namu pane equalize
namu pane swap --pane_id pane:1 --target_pane_id pane:2
namu pane break --pane_id pane:3
namu pane send_keys "npm test\n"
namu pane read_screen --lines 50
namu pane zoom
namu pane unzoom
namu pane last
namu pane list
namu pane new_browser_tab
namu pane new_markdown_tab
namu pane pin
namu pane unpin

surface.*

namu surface list
namu surface current
namu surface split --direction right
namu surface reorder --surface_id surface:1 --index 0
namu surface drag_to_split --surface_id surface:1 --direction right
namu surface move --surface_id surface:1 --pane_id pane:2
namu surface move --surface_id surface:1 --workspace_id workspace:3
namu surface send_text --text "ls\n"
namu surface send_key --key enter
namu surface read_text --lines 100
namu surface close

sidebar.*

# Status pills
namu sidebar set_status build "Tests passing" --icon checkmark.circle --color "#34C759" --priority 10
namu sidebar set_status deploy "Deploying..." --icon arrow.up.circle --color "#007AFF"
namu sidebar clear_status build
namu sidebar list_status

# Progress bar
namu sidebar set_progress 0.75 --label "Building (75%)"
namu sidebar clear_progress

# Structured log
namu sidebar log --level success "All 42 tests passed"
namu sidebar log --level warning "Slow query detected" --source db
namu sidebar log --level error "Build failed" --source ci
namu sidebar clear_log
namu sidebar list_log --limit 50

window.*

namu window list
namu window current
namu window create
namu window focus --id window:1
namu window close --id window:2

browser.*

namu browser open
namu browser navigate --url "https://example.com"
namu browser eval --code "document.title"
namu browser click --selector "#submit"
namu browser type --selector "#input" --text "hello"
namu browser hover --selector ".menu-item"
namu browser get-text --selector "h1"
namu browser get-attr --selector "a" --attribute "href"
namu browser screenshot --path screenshot.png
namu browser back
namu browser forward
namu browser reload
namu browser url
namu browser title
namu browser find --text "search term"

notification.*

namu notification create --title "Build done" --body "All tests passed"
namu notification list
namu notification clear
namu notification jump_to_unread

system.*

namu system ping
namu system version
namu system status
namu system identify
namu system relay_status
namu system render_stats
namu system capabilities --json

debug.*

namu debug layout
namu debug window screenshot --path /tmp/window.png
namu debug panel snapshot --surface_id surface:1
namu debug underflow count
namu debug underflow reset
namu debug flash count --surface_id surface:1
namu debug flash reset
namu debug render_stats --surface_id surface:1

Flat Command Aliases

namu version
namu list-workspaces
namu new-workspace
namu list-panes
namu send
namu read-screen
namu notify

SSH Remote Workspace

namu ssh user@host
namu ssh user@host --port 2222
namu ssh user@host --identity ~/.ssh/id_ed25519 --no-focus

Special Entry Points

Claude Hook Integration

namu claude-hook session-start
namu claude-hook prompt-submit
namu claude-hook stop
namu claude-teams

Codex Integration

namu codex install-hooks
namu codex uninstall-hooks
namu codex-hook session-start
namu codex-hook prompt-submit

OpenCode Integration

namu opencode <command>
namu omo <command>

TMux Compatibility

37 tmux-compat commands bridge common tmux patterns to Namu commands:

namu __tmux-compat split-window -h
namu __tmux-compat split-window -v
namu __tmux-compat new-window
namu __tmux-compat select-window -t 0
namu __tmux-compat send-keys "command" Enter
namu __tmux-compat list-windows
namu __tmux-compat list-panes
(and 30+ more tmux commands)

Examples

Create a workspace and split it

WS=$(namu workspace create --title "Dev" --json | python3 -c \
  "import sys,json; print(json.load(sys.stdin)['result']['id'])")

namu workspace select --id "$WS"
namu pane split --direction vertical

Use short refs in a script

# No UUID bookkeeping needed
namu workspace select --id workspace:1
namu pane swap --pane_id pane:1 --target_pane_id pane:2
namu surface move --surface_id surface:3 --pane_id pane:1

Monitor a build with sidebar status

namu sidebar set_status build "Running..." --icon arrow.triangle.2.circlepath --color "#FF9500"
npm test && \
  namu sidebar set_status build "Passed" --icon checkmark.circle.fill --color "#34C759" || \
  namu sidebar set_status build "Failed" --icon xmark.circle.fill --color "#FF3B30"

Run commands and read screen state

namu pane send_keys "npm start\n"
namu pane read_screen --json