npm package: @nuucognition/orbh-cli
Description: 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.
Latest version: 0.1.0-dev.1

# @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

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

After installation, the `orbh` command is available globally.

## Quick Start

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

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

#### `orbh kill <id>`

Terminate a running session process.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

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

#### `orbh respond <id> <response>`

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

```bash
orbh respond a1b2c3d4 "Fix all 3 issues"
```

#### `orbh requests <id>`

View all request/response pairs for a session.

```bash
orbh requests a1b2c3d4
```

### Session Lifecycle

#### `orbh launch <runtime> <prompt>`

Launch a new headless agent session.

```bash
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.

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

#### `orbh interactive <runtime> [prompt]`

Launch an interactive agent TUI with Orbh session tracking.

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

#### `orbh export <id>`

Export a session transcript to the Mesh.

```bash
orbh export a1b2c3d4
```

## Programmatic Usage

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

```typescript
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

```typescript
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