@nuucognition/orbh-cli

Standalone CLI for Orbh — the meta-harness orchestration system for AI agent sessions. Provides 14 commands for managing agent session lifecycle, inspecting transcripts, streaming live sessions, and communicating with running agents.

Installation

npm install -g @nuucognition/orbh-cli
# or
pnpm add -g @nuucognition/orbh-cli

After installation, the orbh command is available globally.

Quick Start

# List recent sessions
orbh list

# Inspect a specific session (full or partial ID)
orbh inspect a1b2c3d4

# Stream a live session transcript
orbh watch a1b2c3d4

# Set a session's status
orbh status a1b2c3d4 finished

# Store a result and mark session finished
orbh return a1b2c3d4 "Task completed successfully"

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | ORBH_SESSIONS_DIR | .orbh/sessions (relative to cwd) | Directory containing session JSON files | | ORBH_CWD | process.cwd() | Working directory for resolving transcript paths |

Commands

All commands support an optional --path / -p flag to override the sessions directory.

Session Inspection

orbh list

List all agent sessions with status, runtime, duration, and title.

orbh list              # Last 30 sessions
orbh list -a           # All sessions
orbh list -s           # Include token/turn stats
orbh list -S blocked   # Filter by status
orbh list -r claude    # Filter by runtime
orbh list -q "auth"    # Search by title/description
orbh list -i           # Interactive sessions only

| Option | Description | |--------|-------------| | -a, --all | Show all sessions (default: last 30) | | -s, --stats | Include turn and token counts | | -S, --status <status> | Filter by session status | | -r, --runtime | Filter by runtime | | -q, --search <query> | Search titles and descriptions | | -i, --interactive | Show only interactive sessions |

orbh inspect <id>

Deep inspection of a single session. Shows full metadata, run history, request/response pairs, and interface keys.

orbh inspect a1b2c3d4

Session IDs can be specified as full UUIDs or 8+ character prefixes.

orbh stats <id>

Detailed session statistics including turns, token usage, tool frequency, and files touched.

orbh stats a1b2c3d4
orbh stats a1b2c3d4 --files   # Show full file paths

orbh watch <id>

Stream a live session transcript to the terminal in real time with colored output. Shows human messages, agent responses, thinking blocks, tool calls, and subagent activity.

orbh watch a1b2c3d4

Session Control

orbh heal

Fix sessions stuck in non-terminal states with stale PIDs. Detects dead processes and transitions orphaned sessions to appropriate terminal states.

orbh heal              # Fix stuck sessions
orbh heal --dry-run    # Preview what would be healed

orbh kill <id>

Terminate a running session process.

orbh kill a1b2c3d4

orbh register <id> <title> <description>

Set a human-readable title and description on a session. Used by agents at startup to identify themselves.

orbh register a1b2c3d4 "Auth Fix" "Implementing the authentication fix from Task 205"

Status Management

orbh status <id> [value]

Get or set session status. When setting, validates the transition.

orbh status a1b2c3d4              # Get current status
orbh status a1b2c3d4 in-progress  # Set status

Valid statuses: queued, in-progress, blocked, deferred, finished, failed, cancelled

orbh return <id> <result>

Store the final result and mark the session as finished. This is how agents deliver their output.

orbh return a1b2c3d4 "Completed all 5 requirements. Moved task to review."

Interface Management

The session interface is a key-value store that agents use to communicate progress and state to humans and dashboards.

orbh set <id> <key> <value>

Write a key-value pair to the session interface.

orbh set a1b2c3d4 phase "implementing"
orbh set a1b2c3d4 progress "3/5 requirements"
orbh set a1b2c3d4 task "(Task) 341 Pre-Pass Title"

orbh get <id> <key>

Read a value from the session interface. Outputs to stdout.

orbh get a1b2c3d4 phase    # → implementing

orbh artifact <id> <path>

Track a created or modified artifact in the session interface. Used by agents to register Mesh artifacts they produce.

orbh artifact a1b2c3d4 "(Report) 012 Task Review"

Human Interaction

orbh ask <id> <question>

Ask a blocking question and wait for a response. Sets session to blocked, sends a macOS notification, and polls until the human responds via orbh respond. Times out after 60 seconds.

response=$(orbh ask a1b2c3d4 "Should I fix all 3 issues or just the critical one?")
echo "$response"

orbh request <id> <question>

Post a deferred question and exit immediately. Sets session to deferred and sends a macOS notification. The agent exits; when the human responds, the session can be resumed.

orbh request a1b2c3d4 "What priority should this fix be?"

orbh respond <id> <response>

Answer a pending question on a session (used by humans).

orbh respond a1b2c3d4 "Fix all 3 issues"

orbh requests <id>

View all request/response pairs for a session.

orbh requests a1b2c3d4

Session Lifecycle

orbh launch <runtime> <prompt>

Launch a new headless agent session.

orbh launch claude "Implement the auth fix described in Task 205"
orbh launch codex "Review the API changes" --model gpt-4
orbh launch claude "Fix the bug" --max-turns 50 --title "Bug Fix"

| Option | Description | |--------|-------------| | --continues <id> | Link as continuation of another session | | --max-turns <n> | Maximum agent turns | | --model <model> | Model override | | --title <title> | Pre-set session title | | --description <desc> | Pre-set session description |

orbh resume <id> [prompt]

Resume an existing session, adding a new run.

orbh resume a1b2c3d4
orbh resume a1b2c3d4 "Continue with the remaining requirements"

orbh interactive <runtime> [prompt]

Launch an interactive agent TUI with Orbh session tracking.

orbh interactive claude
orbh interactive claude "Help me debug this issue"

orbh export <id>

Export a session transcript to the Mesh.

orbh export a1b2c3d4

Programmatic Usage

The CLI can be embedded into other Commander.js programs:

import { Command } from 'commander';
import { registerPureOrbhCommands } from '@nuucognition/orbh-cli';

const program = new Command('my-tool');

registerPureOrbhCommands(program.command('orbh'), {
  resolveContext: async (path) => ({
    sessionsDir: path ?? '/custom/sessions/dir',
    transcriptCwd: process.cwd(),
  }),
});

program.parse();

Exports

import {
  // CLI setup
  registerPureOrbhCommands,
  createStandaloneOrbhCommand,
  createStandaloneOrbhProgram,
  resolveStandaloneContext,
  type OrbhCliContext,
  type RegisterPureOrbhCommandsOptions,

  // Formatting utilities
  shortId,
  formatLocalTime,
  isTerminalStatus,
} from '@nuucognition/orbh-cli';

| Export | Description | |--------|-------------| | registerPureOrbhCommands(command, options) | Register all Orbh subcommands onto a Commander command | | createStandaloneOrbhCommand() | Create a ready-to-use Commander command with all subcommands | | createStandaloneOrbhProgram() | Create a full program with version from package.json | | resolveStandaloneContext() | Resolve ORBH_SESSIONS_DIR and ORBH_CWD from environment | | shortId(id) | Truncate a UUID to 8 characters | | formatLocalTime(iso) | Format an ISO timestamp to local time | | isTerminalStatus(status) | Check if a status string is terminal |

License

MIT