# CLI The CLI is both an operator tool and an agent-readable interface to the platform. It can work entirely locally or point at the hosted gateway. ## How do I check my setup status? Run `toolrouter --status` or `toolrouter status` to see your version, auth state, credit balance, and tool count at a glance. Use `--format json` for machine-readable output that agents can parse programmatically. Get everything at a glance — version, auth, credits, and tool count: ```bash toolrouter --status toolrouter status toolrouter status --format json ``` This is the fastest way to verify your setup is working. The JSON format is useful for agents that need to check auth and credit state programmatically. ## How does configuration work? ToolRouter stores config in `~/.toolrouter/config.json` with fields for `gateway_url`, `api_key`, `plugins`, and `provider_keys`. Mode is automatic: local mode when pointing to localhost, remote mode when pointing to a non-localhost server with an API key. ToolRouter stores config in `~/.toolrouter/config.json`. Important fields: - `gateway_url` - `api_key` - `plugins` - `provider_keys` Mode selection is simple: - local mode: `gateway_url` is `http://localhost:3141` or no remote key is configured - remote mode: `gateway_url` points to a non-localhost server and `api_key` is present ## How do I read docs in the terminal? Run `toolrouter docs` to see the docs index, `toolrouter docs quickstart` for a specific page, or `toolrouter docs --list` to list all available pages. This is the fastest way for agents to read the same onboarding content humans see on the website. The docs section is shared between the website and CLI: ```bash toolrouter docs toolrouter docs quickstart toolrouter docs --list toolrouter docs integration --format json ``` This is the fastest way for an agent to read the same onboarding content a human sees on the website. ## How do I discover and search tools? Run `toolrouter tools` to list all tools, `toolrouter search domain` to search by keyword, `toolrouter info domain-search` for detailed tool info, or `toolrouter credentials` to check which tools need upstream API keys. ```bash toolrouter tools toolrouter search domain toolrouter info domain-search toolrouter credentials ``` ## How do I call tools from the CLI? Run `toolrouter call ` with input as direct flags (`--url https://example.com`), inline JSON (`--input '{...}'`), or a file (`--input-file data.json`). Add `-o report.json` to save the full result to a file. ```bash toolrouter call seo analyze_page --url https://example.com toolrouter call domain-search search_domains --query "tool router" --limit 5 toolrouter call web-search search --input '{"query":"toolrouter"}' ``` Input can be passed three ways: - inline JSON with `--input` - a JSON file with `--input-file` - direct flags like `--url https://example.com` ### Saving output to a file Use `-o` / `--output` to write the full result JSON to a file: ```bash toolrouter call seo analyze_page --url https://example.com -o report.json toolrouter call web-search search --query "MCP tools" --output results.json ``` The result is written as JSON regardless of display format. This is useful for agents that need to save results for downstream processing — a Cowork agent saving an SEO report to the Desktop, or a CI pipeline archiving tool output. ## How do I pipe output and automate? The CLI auto-detects non-TTY mode and strips all ANSI colors, formatting, and spinners. Standard Unix patterns work: pipe to `jq`, redirect to files, or chain with other tools. Output is clean plain text suitable for parsing or storage. The CLI detects when stdout is not a terminal (piped to a file, another process, or redirected). In non-TTY mode: - All ANSI colors and formatting are stripped automatically - Spinners are suppressed (no control characters in output) - Output is clean plain text suitable for parsing or storage This means standard Unix patterns work cleanly: ```bash # Pipe to jq toolrouter call web-search search --query "AI tools" --format json | jq '.output' # Save to file via redirect toolrouter --status > status.txt # Chain with other tools toolrouter tools --format json | jq '.[].name' ``` Combined with `-o`, agents can save structured results to a known path without worrying about ANSI artifacts in the output. ## How do I authenticate? Run `toolrouter login --api-key --gateway https://api.toolrouter.com` to authenticate, `toolrouter whoami` to verify, or `toolrouter logout` to clear credentials. ```bash toolrouter login --api-key --gateway https://api.toolrouter.com toolrouter whoami toolrouter logout ``` ## How do I manage API keys? Create, list, and revoke API keys from the CLI. The same operations are available via MCP (`list_api_keys`, `create_api_key`, `revoke_api_key`), REST API, and the dashboard. ```bash toolrouter keys create --name "My Bot" toolrouter keys list toolrouter keys list --format json toolrouter keys get toolrouter keys revoke ``` ## How do I manage billing? Check your balance, top up credits, and view billing history. The same operations are available via MCP (`check_balance`, `top_up_credits`), REST API, and the dashboard. ```bash toolrouter billing balance # Check credit balance toolrouter billing balance --format json # Machine-readable balance toolrouter billing checkout --amount 20 # Generate Stripe checkout link ``` ## How do I check usage? View usage summary by tool/skill and detailed call history. The same data is available via MCP (`get_usage_summary`, `get_usage_history`), REST API, and the dashboard. ```bash toolrouter usage # Usage summary (all time) toolrouter usage --period month # Filter by period (day/week/month/all) toolrouter usage --format json # Machine-readable summary toolrouter billing history # Detailed call history toolrouter billing history --limit 20 # Limit records toolrouter billing history --format json # Machine-readable history ``` ## How do I manage provider keys? Store BYOK (Bring Your Own Key) provider keys. The same operations are available via MCP (`save_credential`, `list_credentials`, `delete_credential`), REST API, and the dashboard. ```bash toolrouter providers add firecrawl --key fc_xxx toolrouter providers add serper --key sp_xxx toolrouter providers list toolrouter providers remove firecrawl ``` ## How do I run a local server? Run `toolrouter serve --transport stdio` when an MCP client launches ToolRouter directly, or `toolrouter serve --transport http --port 3141` for REST and stateless MCP over HTTP. ```bash toolrouter serve --transport stdio toolrouter serve --transport http --port 3141 ``` Use `stdio` when an MCP client launches ToolRouter directly. Use `http` when you want REST and stateless MCP over HTTP. ## How do I author and test tools? Run `toolrouter init my-tool my_skill` to scaffold, `toolrouter validate` to check the manifest, and `toolrouter test seo` to execute all examples as integration tests. Use `--knowledge` for RAG support or `--plugin` for standalone npm packages. ```bash toolrouter init my-tool my_skill toolrouter init my-tool --knowledge toolrouter init my-tool --plugin toolrouter validate toolrouter test seo toolrouter install my-tool-plugin toolrouter uninstall my-tool-plugin ``` If you are adding new tools, continue with [Building Tools](/docs/building-tools).