Get started

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 <tool> <skill> 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 <KEY> --gateway https://api.toolrouter.com to authenticate, toolrouter whoami to verify, or toolrouter logout to clear credentials.

bash
toolrouter login --api-key <YOUR_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 <key-id>
toolrouter keys revoke <key-id>

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.