# @uncaged/nerve-cli

Command-line interface for the [nerve](../../README.md) observation engine.

## Install

```bash
pnpm add -g @uncaged/nerve-cli
# or
npx @uncaged/nerve-cli
```

Requires Node.js ≥ 22.5.

## Commands

### Workspace

```bash
nerve init                  # Initialize a nerve workspace (installs deps, scaffolds config)
nerve validate              # Validate nerve.yaml configuration
```

### Daemon management

```bash
nerve daemon start          # Start the daemon (background)
nerve daemon stop           # Stop the daemon
nerve daemon status         # Show pid, uptime, sense names from nerve.yaml (process must exist)
nerve daemon restart        # Stop then start
nerve daemon logs           # Tail daemon process logs (file under workspace logs/)
```

### Development

```bash
nerve dev                   # Foreground kernel with file watcher + IPC (Ctrl+C stops)
```

### Querying & status

```bash
nerve logs                  # Tail or page the daemon text log file (path in footer; default ~/.uncaged-nerve/logs/nerve.log)
nerve status                # Short daemon health summary (aliases daemon status)
```

Structured rows in `data/logs.db` are surfaced via **`nerve workflow inspect`** / **`nerve workflow list`** (and `LogStore` in code), not via `nerve logs`.

### Sense

```bash
nerve sense list            # List senses (live fields from daemon IPC when running)
nerve sense trigger <name>  # IPC trigger-sense — queue a compute for that sense
```

Sense state is persisted as JSON under `data/senses/<name>.json` by the sense worker after each successful compute.

### Store maintenance

```bash
nerve store archive         # Move old log rows to JSONL under data/archive/logs/… (optional --vacuum)
```

### Workflows

```bash
nerve workflow list         # Queued/started runs (add --all for terminal states; --workflow, --limit, --offset)
nerve workflow inspect <runId>   # Run metadata + paginated workflow log lines
nerve workflow thread <runId>    # Role rounds from persisted messages (--before, --budget)
nerve workflow trigger <name>    # IPC trigger-workflow (daemon must be running)
                                   # Optional JSON: --payload '{"prompt":"…","maxRounds":50}'
```

`nerve workflow trigger` sends a `trigger-workflow` line on the daemon Unix socket (same protocol as `@uncaged/nerve-core` / `parseDaemonIpcRequest`). It does not read `nerve.yaml` workflow definitions beyond what the running daemon already loaded.

### Top-level aliases

```bash
nerve start    → nerve daemon start
nerve stop     → nerve daemon stop
nerve status   → nerve daemon status
nerve logs     → nerve daemon logs
```

## License

MIT