@gwop/agentrouter-cli

Headless CLI for Agentrouter.

This repo is the installable operator surface for the hosted Agentrouter API. It does not replace the server. It wraps the hosted API in a cleaner terminal workflow for humans and agents.

Status

This is the first public scaffold.

Available now:

• agentrouter start
• agentrouter login <base|solana>
• agentrouter login complete <auth-intent-id>
• agentrouter status
• agentrouter plans
• agentrouter ask free
• agentrouter ask paid
• agentrouter subscribe <base|solana>
• agentrouter subscribe confirm <checkout-id>
• agentrouter logout

Install

npm install -g @gwop/agentrouter-cli

Quick Start

agentrouter start
agentrouter login solana
agentrouter login complete ai_123
agentrouter plans
agentrouter ask free "hello"

Global Options

| Flag | Description | Default | | --- | --- | --- | | --server <url> | Agentrouter API base URL | https://api.agentrouter.lol | | --timeout <ms> | Request timeout | 30000 | | --json | Machine-readable output | false | | --trace-file <path> | Write HTTP traces to a specific JSONL file | ~/.config/agentrouter/.local/http-trace.jsonl | | --trace-raw | Disable default trace redaction | false | | --debug | Show verbose error context | false |

Current Commands

agentrouter start

Checks API health and readiness, loads local session state if present, and prints the current product state with suggested next actions. It also surfaces any saved pending auth or checkout flow that can be resumed.

agentrouter status

Shows current local and remote session state. If no local session exists, it prints the disconnected state cleanly. It also shows any saved in-flight auth or checkout state.

agentrouter plans

Fetches the public Agentrouter catalog and renders the current free tier and subscription offer.

agentrouter login <base|solana>

Starts the wallet auth challenge for the requested chain and prints the payable x402 URL. It exits immediately with the auth intent id and next command.

agentrouter login complete <auth-intent-id>

Completes auth after the external x402 payment has settled, stores the local session, and prints the resulting account state.

agentrouter ask free

Runs one authenticated free-tier inference request and shows the remaining free quota.

agentrouter ask paid

Runs one authenticated paid inference request for an active subscriber.

agentrouter subscribe <base|solana>

Creates a checkout, fetches the payer-facing Gwop invoice, selects the requested chain, and prints the payable x402 URL with the checkout id and invoice id.

agentrouter subscribe confirm <checkout-id>

Checks whether the subscription checkout has settled. If it has, the CLI refreshes /v1/me and updates local state. If it has not, the CLI returns the current checkout status without blocking.

agentrouter logout

Revokes the remote session and clears local session state.

For Agents

The CLI ships with a first-class skill in skills/SKILL.md. Read that before using the binary from an agentic workflow.

Local Development

npm install
npm run lint
npm run typecheck
npm run test
npm run build
node dist/bin/agentrouter.js start

Payment Note

The current CLI does not embed a wallet stack.

For auth and subscription flows the CLI emits payable x402 URLs and expects an external payer to settle them. It does not try to own the wallet or block the shell waiting for payment.

Resume State

The CLI persists in-flight auth and checkout state to:

~/.config/agentrouter/flows.json

That file lets agentrouter login complete <auth-intent-id> and agentrouter subscribe confirm <checkout-id> resume cleanly after an interrupted terminal or external payer hop.

Tracing

The CLI writes HTTP traces by default to:

~/.config/agentrouter/.local/http-trace.jsonl

By default those traces redact bearer tokens, session ids, and wallet addresses. Use --trace-file <path> to write elsewhere, and --trace-raw only when you explicitly want an unredacted local trace.

Local State

The CLI automatically maintains local JSON state under:

~/.config/agentrouter/

Key files:

• session.json for the active local session
• flows.json for in-flight auth and checkout state
• .local/http-trace.jsonl for low-level HTTP traces
• .local/history.jsonl for command history, inputs, outputs, exit codes, and usage summaries

History is written automatically on every CLI run. By default it stores sanitized stdout and stderr so sensitive values like bearer tokens are not persisted in plain text.

Output Contract

• human-readable stdout by default
• plain-text stderr for errors
• --json for machine-readable output
• stable exit codes

License

MIT