routstrd/SKILL.md

# routstrd CLI Reference

Routstr daemon — a Bun-based CLI tool that runs a background HTTP server for the Routstr protocol. It integrates with `cocod` for Cashu wallet management and routes LLM requests to available providers.

## Quick Start

```sh
routstrd onboard          # Initialize (creates config, sets up cocod)
routstrd start            # Start the daemon
routstrd stop             # Stop the daemon
```

After onboarding, the daemon listens at `http://localhost:8008` and exposes an OpenAI-compatible API.

## Commands

### `routstrd onboard`

Initialize routstrd for the first time:
- Creates `~/.routstrd/` config directory
- Creates `~/.routstrd/config.json` with defaults (port 8008, apikeys mode)
- Installs `cocod` globally via bun if not present
- Runs `cocod init` to set up the wallet
- Starts the daemon and configures integrations

### `routstrd start`

Start the background daemon process.

| Option | Description |
|--------|-------------|
| `--port <port>` | Port to listen on (default: 8008) |
| `-p, --provider <provider>` | Default provider to use |

### `routstrd stop`

Stop the background daemon.

### `routstrd restart`

Restart the daemon (stops if running, then starts).

| Option | Description |
|--------|-------------|
| `--port <port>` | Port to listen on |
| `-p, --provider <provider>` | Default provider to use |

### `routstrd status`

Check daemon and wallet status. Returns JSON with current state.

### `routstrd balance`

Get wallet and API key balances. Shows per-mint wallet balances, per-key API balances, and a grand total (all in sats).

### `routstrd models`

List available routstr21 models (discovered via Nostr).

| Option | Description |
|--------|-------------|
| `-r, --refresh` | Force refresh models from Nostr |

### `routstrd usage`

Show recent usage logs and total sats cost.

| Option | Default | Description |
|--------|---------|-------------|
| `-n, --limit <number>` | 10 | Number of recent entries (max 1000) |

Shows timestamp, model, provider, sats cost, token counts, and request ID for each entry.

### `routstrd providers`

List and manage providers (subcommand required).

#### `routstrd providers list`

List all providers with their enabled/disabled status. Shows index, status, and base URL.

```
Providers (12 total, 2 disabled):

  [0] enabled   https://provider1.example.com
  [1] enabled   https://provider2.example.com
  [2] DISABLED  https://provider3.example.com
```

#### `routstrd providers disable <indices...>`

Disable providers by their index numbers.

```sh
routstrd providers disable 0 2 5
```

#### `routstrd providers enable <indices...>`

Enable providers by their index numbers.

```sh
routstrd providers enable 0 2 5
```

### `routstrd clients`

List and manage API clients (subcommand required).

| Option | Description |
|--------|-------------|
| `--manual-refresh` | Refresh routstr21 models and all client integrations now |
| `--disable-automatic-refresh` | Disable the daemon's scheduled refresh job |
| `--enable-automatic-refresh` | Re-enable the daemon's scheduled refresh job |

The daemon refreshes models and client integrations on a schedule (every 21 minutes by default). Use `--manual-refresh` to do it on demand, and `--disable-automatic-refresh` to stop the scheduled job — the setting is stored in the daemon's `config.json` (`autoRefresh.enabled`) and takes effect without a restart.

```sh
routstrd clients --manual-refresh              # refresh models + integrations now
routstrd clients --disable-automatic-refresh   # no scheduled refresh
routstrd clients --enable-automatic-refresh    # scheduled refresh back on
```

#### `routstrd clients list`

List all registered clients with their ID, name, API key, and creation date.


#### `routstrd clients add`

Add a new client or set up a client integration.

| Option | Description |
|--------|-------------|
| `-n, --name <name>` | Client name (required when not using integration flags) |
| `--opencode` | Set up OpenCode integration |
| `--openclaw` | Set up OpenClaw integration |
| `--pi-agent` | Set up Pi Agent integration |
| `--claude-code` | Set up Claude Code integration |

```sh
routstrd clients add --opencode --pi-agent --claude-code  # multiple integrations
routstrd clients add -n "My App"                            # generic client
```

Returns the client ID and API key for use with the OpenAI-compatible API.

#### `routstrd clients delete <id>`

Delete a registered client by its ID.

### `routstrd npubs`

Manage registered npubs and their roles/names (subcommand required). Management commands route through the auth proxy (`--auth-url`) and use NIP-98 auth.

| Command | Description |
|---------|-------------|
| `routstrd npubs list` | List registered npubs with role and display name |
| `routstrd npubs register [--name <name>]` | Register yourself as the first admin (bootstrap only) |
| `routstrd npubs add <npub> [--role <role>] [--name <name>]` | Add an npub (accepts hex or npub1...) |
| `routstrd npubs update <npub> [--role <role>] [--name <name>]` | Update role and/or name (admin only) |
| `routstrd npubs delete <npub>` | Delete an npub |

### `routstrd remote <url>`

Configure a remote daemon URL. Generates a Nostr identity (nsec/npub) for NIP-98 authentication automatically.

```sh
routstrd remote https://your-remote-daemon.com
```

### `routstrd refresh`

Refresh routstr21 models from Nostr and re-run integrations for all registered clients. Equivalent to `routstrd clients --manual-refresh`.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `port` | number | 8008 | Daemon HTTP port |
| `provider` | string\|null | null | Default provider URL |
| `daemonUrl` | string\|null | null | Remote daemon URL |
| `nsec` | string\|null | null | Nostr secret key for NIP-98 auth |
| `cocodPath` | string\|null | null | Custom path to cocod executable |
| `mode` | string | `"apikeys"` | Client mode (`apikeys` or `xcashu`) |
| `autoRefresh` | object | `{ enabled: true }` | Scheduled refresh job settings (`enabled`, `intervalMs`) |

| Variable | Default | Description |
|----------|---------|-------------|
| `ROUTSTRD_DIR` | `~/.routstrd` | Config directory |
| `ROUTSTRD_WALLET_DIR` | `~/.routstrd/wallet` | In-process Cashu wallet data directory |
| `ROUTSTRD_WALLET_PID` | `<wallet>/wallet.pid` | In-process wallet lock path |
| `COCOD_DIR` | `~/.cocod` | Legacy external cocod compatibility directory |

### `routstrd mode`

Interactive prompt to set the client mode:
1. **lazyrefund/apikeys** (default) — Pseudonymous accounts kept with Routstr nodes, refunded after 5 mins if unused.
2. **xcashu** (coming soon) — Balances never kept with nodes, all refunded in response.

Changing mode restarts the daemon automatically.

### `routstrd monitor`

Open an interactive TUI (htop-like) for usage monitoring.

### `routstrd logs`

View daemon logs.

| Option | Default | Description |
|--------|---------|-------------|
| `-f, --follow` | false | Follow log output (like `tail -f`) |
| `-c, --coco` | false | Show Cashu wallet-engine (coco) logs instead of daemon logs |
| `-n, --lines <number>` | 50 | Number of lines to show |

Log files are stored at `~/.routstrd/logs/YYYY-MM-DD.log`. Wallet-engine (Cashu/coco) diagnostics go to a separate `~/.routstrd/coco-logs/YYYY-MM-DD.log` so they don't pollute the main daemon logs.

## Wallet Commands

New wallets automatically trust `https://mint.cubabitcoin.org` as their default mint. The default is used when a wallet command does not include `--mint-url`.

### `routstrd wallet status`

Check wallet status.

### `routstrd wallet unlock <passphrase>`

Unlock the wallet with a passphrase.

### `routstrd wallet balance`

Get wallet balance.

### `routstrd wallet receive cashu <token>`

Receive funds via a Cashu token.

### `routstrd wallet receive bolt11 <amount>`

Create a Lightning invoice to receive funds. Displays a QR code.

| Option | Description |
|--------|-------------|
| `--mint-url <url>` | Mint URL to use |

### `routstrd wallet send cashu <amount>`

Create a Cashu token to send.

| Option | Description |
|--------|-------------|
| `--mint-url <url>` | Mint URL to use |

### `routstrd wallet send bolt11 <invoice>`

Pay a Lightning invoice.

| Option | Description |
|--------|-------------|
| `--mint-url <url>` | Mint URL to use |

### `routstrd wallet mints list`

List configured wallet mints.

### `routstrd wallet mints add <url>`

Add a new mint by URL.

### `routstrd wallet mints set-default <url>`

Set the persistent default mint. If necessary, the mint is added as trusted first.

### `routstrd wallet mints info <url>`

Get info about a specific mint.

## Daemon API

The daemon exposes an OpenAI-compatible HTTP API at `http://localhost:8008`:

### `GET /health`

Health check endpoint.

### `GET /v1/models`

List available models (OpenAI-compatible).

### `POST /v1/chat/completions`

Route a chat completion request.

```json
{
  "model": "model-id",
  "messages": [{ "role": "user", "content": "Hello" }],
  "stream": false
}
```

## Configuration

Config file: `~/.routstrd/config.json`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `port` | number | 8008 | Daemon HTTP port |
| `provider` | string\|null | null | Default provider URL |
| `cocodPath` | string\|null | null | Custom path to cocod executable |
| `mode` | string | `"apikeys"` | Client mode (`apikeys` or `xcashu`) |
| `autoRefresh` | object | `{ enabled: true }` | Scheduled refresh job settings (`enabled`, `intervalMs`) |

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ROUTSTRD_DIR` | `~/.routstrd` | Config directory |
| `ROUTSTRD_SOCKET` | `~/.routstrd/routstrd.sock` | IPC socket path |
| `ROUTSTRD_PID` | `~/.routstrd/routstrd.pid` | PID file path |

## Remote Mode

When `daemonUrl` is configured, commands connect to a remote daemon instead of a local one:
- Client names are suffixed with the last 7 chars of your npub
- All requests are automatically NIP-98 signed using your local nsec
- Local-only commands (`onboard`, `start`, `restart`, `mode`, `logs`, `service`) are disabled

## Pi Integration

When `routstrd onboard` runs, it automatically configures a `routstr` provider in `pi`'s `models.json` with an OpenAI-compatible base URL and API key. This allows pi (the AI coding agent) to use Routstr providers seamlessly.

## File Locations

| Path | Description |
|------|-------------|
| `~/.routstrd/config.json` | Configuration |
| `~/.routstrd/routstr.db` | SQLite database |
| `~/.routstrd/routstrd.sock` | IPC socket |
| `~/.routstrd/routstrd.pid` | PID file |
| `~/.routstrd/logs/YYYY-MM-DD.log` | Daily daemon log files |
| `~/.routstrd/coco-logs/YYYY-MM-DD.log` | Daily Cashu wallet-engine (coco) log files |