routstrd 0.4.8 → 0.4.10

package/README.md

@@ -19,15 +19,56 @@ For team-based routing, see [routstrd-auth](https://github.com/Routstr/routstrd-
 
 ## Requirements
 
-- [Bun](https://bun.sh) runtime
+The standalone release does not require Bun, Node.js, or npm. Installing from
+npm or running from source requires the [Bun](https://bun.sh) runtime.
+
+## Installation
+
+### Step 1: Install
+
+**Standalone binary (recommended):**
+
+Installs the standalone executable for Linux or macOS (x64 or arm64) into
+`$HOME/.local/bin`. No Bun, Node.js, or npm required.
 
 ```sh
-curl -fsSL https://bun.com/install | bash
+curl -fsSL https://github.com/Routstr/routstrd/releases/latest/download/install.sh | sh
 ```
 
-## Installation
+Pin a version, change the install directory, or print the resolved asset without
+installing anything:
 
-### Step 1: Install
+```sh
+curl -fsSL https://github.com/Routstr/routstrd/releases/latest/download/install.sh \
+  | sh -s -- --version 0.4.9 --dir /usr/local/bin
+```
+
+The installer downloads the release archive, verifies it against the release
+`SHA256SUMS`, and only replaces an existing `routstrd` once the checksum matches
+and the extracted binary reports the expected version.
+
+<details>
+<summary>Manual install</summary>
+
+Download the archive for your operating system and architecture from the
+[latest GitHub Release](https://github.com/Routstr/routstrd/releases/latest).
+Release archives are available for Linux and macOS on x64 and arm64.
+
+```sh
+grep "routstrd-v0.4.9-linux-x64.tar.gz" SHA256SUMS | shasum -a 256 -c -
+tar -xzf routstrd-v0.4.9-linux-x64.tar.gz
+mkdir -p "$HOME/.local/bin"
+install -m 755 routstrd "$HOME/.local/bin/routstrd"
+```
+
+Substitute the version, platform, and architecture for the archive you
+downloaded, and ensure `$HOME/.local/bin` is on `PATH`.
+
+</details>
+
+Installing the standalone binary is preferred over the npm package: the npm
+package runs through the Bun runtime, while the standalone executable has no
+runtime dependency.
 
 **Global with bun:**
 ```sh
@@ -103,6 +144,17 @@ Test connection:
 routstrd ping
 ```
 
+Refresh models and client integrations on demand:
+```sh
+routstrd clients --manual-refresh   # same as `routstrd refresh`
+```
+
+Turn the daemon's scheduled refresh on or off (no restart needed):
+```sh
+routstrd clients --disable-automatic-refresh
+routstrd clients --enable-automatic-refresh
+```
+
 Stop the daemon:
 ```sh
 routstrd stop
@@ -139,6 +191,20 @@ The daemon exposes an HTTP server (default port 8008) with the following endpoin
 GET /health
 ```
 
+#### Automatic Refresh Settings
+```
+POST /settings/auto-refresh
+```
+
+Request body:
+```json
+{ "enabled": false }
+```
+
+Enables or disables the scheduled refresh job. Persisted to the daemon's
+`config.json` as `autoRefresh.enabled` and picked up on the next tick, so no
+daemon restart is required.
+
 #### Route Request
 ```
 POST /
@@ -186,10 +252,18 @@ Configuration is stored in `~/.routstrd/config.json`:
   "port": 8008,
   "host": "127.0.0.1",
   "provider": null,
-  "cocodPath": null
+  "cocodPath": null,
+  "autoRefresh": { "enabled": true }
 }
 ```
 
+`autoRefresh.enabled` (default `true`) controls the daemon's scheduled refresh
+job, which re-fetches Nostr events, routstr21 models, and client integrations
+every 21 minutes. Set it to `false` (or run
+`routstrd clients --disable-automatic-refresh`) to turn the schedule off and
+refresh manually with `routstrd clients --manual-refresh`. `autoRefresh.intervalMs`
+overrides the 21-minute interval.
+
 ### Environment Variables
 
 - `ROUTSTRD_DIR` - Config directory (default: `~/.routstrd`)
@@ -213,6 +287,33 @@ Run daemon:
 bun run start
 ```
 
+Build a standalone executable for the current platform:
+
+```sh
+bun run build:binary
+./dist/routstrd --version
+```
+
+Standalone installations update directly from GitHub Releases with
+`routstrd update`. npm installations continue to update through Bun. PM2 is an
+optional external dependency used only by `routstrd service`; normal daemon
+operation does not require it.
+
+When an update finds a process on the configured daemon port, it only stops that
+process if the wallet PID file confirms a live daemon owned by the same routstrd
+configuration. Otherwise the update remains installed, but automatic restart is
+refused so an unrelated daemon is not interrupted.
+
+Existing PM2 registrations created by routstrd 0.4.x continue to work through a
+compatibility daemon entrypoint. Recreate the registration to use the unified
+CLI entrypoint and remove its legacy path dependency:
+
+```sh
+routstrd service uninstall
+routstrd service install
+pm2 save
+```
+
 Typecheck:
 ```sh
 bun run lint
@@ -232,6 +333,24 @@ Set `ROUTSTRD_BASE_URL` to test a daemon at a different address. The script
 makes live provider requests that may spend wallet funds, so it is intentionally
 not part of `bun test`.
 
+### Publishing a standalone release
+
+1. Set a new `package.json` version and commit it. The release tag must be the
+   same version prefixed with `v`, and the tag must not already exist.
+2. Push the tag. The release workflow runs lint and tests, builds Linux and
+   macOS executables for x64 and arm64, smoke-tests them, verifies the archives
+   through `install.sh` itself, and publishes the archives with `SHA256SUMS` and
+   `install.sh`.
+3. Verify all four archives and `install.sh` appear in the GitHub Release and
+   validate each checksum before announcing it.
+4. In disposable environments for each platform, test `--version`, `--help`,
+   foreground startup failure, and background `start`, `status`, and `stop`
+   without Bun on `PATH`.
+5. Test `routstrd service install` and restart behavior with PM2 in a disposable
+   environment. Never run release/update lifecycle tests against a production
+   daemon. When isolation is needed, use both a separate `ROUTSTRD_DIR` and a
+   non-production port in that configuration.
+
 ## Project Structure
 
 ```

package/SKILL.md

@@ -0,0 +1,341 @@
+# 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 |