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

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.

routstrd providers disable 0 2 5

routstrd providers enable <indices...>

Enable providers by their index numbers.

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.

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

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.

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.

{
  "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