> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.agentrouter.to/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentrouter.to/_mcp/server. # CLI The AgentRouter CLI is the best integration surface when a human operator, support engineer, or developer wants to: * inspect the live catalog quickly * reproduce recommendation or execution flows from a terminal * verify payloads before wiring them into an application * run smoke checks in scripts or CI The CLI is intentionally thin. It sits on top of the same TypeScript SDK surface and keeps the same capability-first model: 1. inspect domains and capabilities 2. inspect contracts and routes 3. recommend a route 4. execute explicitly 5. inspect wallet and usage The CLI ships inside the same npm package as the SDK: `@agentrouter/agentrouter`. ## Install Install the package locally when you want repeatable terminal workflows: ```bash npm install @agentrouter/agentrouter ``` Then run: ```bash npx agentrouter --help ``` If you only need a one-off command and do not want to add the package to a project yet: ```bash npx -p @agentrouter/agentrouter agentrouter domains list ``` ## Set Environment ```bash export AGENTIC_API_BASE_URL=https://api.agentrouter.to/api/agentic-api export AGENTIC_API_KEY=aak_... ``` Optional environment variables: ```bash export AGENTIC_API_SESSION_TOKEN=session_... export AGENTIC_API_USER_ID=agentic-local-user export AGENTIC_API_TIMEOUT_MS=20000 ``` ## Recommended CLI Flow ```bash npx agentrouter domains list npx agentrouter capabilities list email npx agentrouter capabilities list models npx agentrouter capabilities list text npx agentrouter capabilities list media npx agentrouter capabilities list geo npx agentrouter capabilities contract email send npx agentrouter capabilities routes models chat-complete npx agentrouter capabilities contract text analyze npx agentrouter capabilities routes text analyze npx agentrouter capabilities routes media image-generate npx agentrouter capabilities routes geo time-current npx agentrouter capabilities routes geo time-convert npx agentrouter capabilities routes web extract npx agentrouter capabilities routes enrichment people-enrich npx agentrouter capabilities routes email send ``` ```bash npx agentrouter recommend email send \ --input '{"optimizationPreferences":["cost","quality"]}' \ --json ``` Save a request body to `send-email.json`: ```json { "to": "maya@example.com", "subject": "Hello from AgentRouter", "html": "

Hello

" } ``` Then execute: ```bash npx agentrouter execute email send \ --input @send-email.json \ --provider resend \ --allow-fallback \ --json ``` ```bash npx agentrouter wallet npx agentrouter usage --limit 20 --json ``` ## Media Example: Pin fal Image Generation fal image generation and edit are live on MPP image routes. Video generation is still recommend/context only: `media.video.generate.fal.mpp` remains gated after upstream paymentauth 524 timeouts reproduced outside AgentRouter. ```bash npx agentrouter routes context media.image.generate.fal.mpp npx agentrouter execute media image-generate \ --input '{"prompt":"Create a clean launch hero image for an AI developer tool","aspectRatio":"16:9","allowFallback":false}' \ --route-key media.image.generate.fal.mpp \ --provider fal \ --json ``` ## Geo Example: Pin Abstract Timezone Abstract Timezone current-time and convert-time routes are live after the May 9, 2026 paid local-production smoke. Inspect route context first so the CLI payload uses `location` for current time, or `fromLocation`, `toLocation`, and optional `datetime` for conversion. ```bash npx agentrouter routes context geo.time.current.abstract-timezone.mpp --json npx agentrouter execute geo time-current \ --input '{"location":"Los Angeles, CA","allowFallback":false}' \ --route-key geo.time.current.abstract-timezone.mpp \ --provider abstract-timezone \ --json npx agentrouter routes context geo.time.convert.abstract-timezone.mpp --json npx agentrouter execute geo time-convert \ --input '{"fromLocation":"Los Angeles, CA","toLocation":"Tokyo, Japan","datetime":"2026-05-08 09:30:00","allowFallback":false}' \ --route-key geo.time.convert.abstract-timezone.mpp \ --provider abstract-timezone \ --json ``` ## Commands ```text agentrouter wallet agentrouter usage [--limit 20] agentrouter domains list|get agentrouter capabilities list|get|routes|contract agentrouter recommend --input agentrouter execute --input agentrouter route --input agentrouter raw ``` ## Input Conventions The CLI accepts request bodies in two forms: Inline JSON: ```bash npx agentrouter recommend email send \ --input '{"optimizationPreferences":["cost"]}' ``` JSON file: ```bash npx agentrouter execute email send \ --input @send-email.json ``` Use `@file.json` when the payload is long, reused across runs, or needs review in version control. ## Broadcast Example: Quote First, Do Not Auto-Send The broadcast domain is a good example of why the CLI should stay recommend-first. ```bash npx agentrouter recommend broadcast message-send \ --input '{"text":"Launch update goes here.","optimizationPreferences":["quality"]}' \ --json npx agentrouter execute broadcast message-quote \ --input '{}' \ --route-key broadcast.message.quote.billboard.mpp \ --json ``` As of May 1, 2026, `broadcast.message.quote` is live, while `broadcast.message.send` remains intentionally gated because one live execute would create a real public post and the latest observed send challenge was about `$40.96`. ## Translation Example: Pin DeepL Rephrase DeepL text rephrase is live after the May 5, 2026 paid route-by-route retest. Inspect route context first so the CLI payload uses DeepL Write fields instead of translate-only fields. ```bash npx agentrouter routes context translation.text.rephrase.deepl.mpp --json npx agentrouter execute translation text-rephrase \ --input '{"text":"Please make this product update friendlier.","targetLanguage":"EN-US","tone":"prefer_friendly"}' \ --route-key translation.text.rephrase.deepl.mpp \ --json ``` ## Models Example: Pin DeepSeek Chat Completion DeepSeek model inference is live through `models.chat.complete.deepseek.mpp`, `models.code.complete.deepseek.mpp`, and `models.list.deepseek.mpp` after the May 5, 2026 production-mode smoke. Inspect route context first so the CLI payload uses a supported model id such as `deepseek-v4-flash`. ```bash npx agentrouter routes context models.chat.complete.deepseek.mpp --json npx agentrouter execute models chat-complete \ --input '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Say AgentRouter DeepSeek smoke OK."}]}' \ --route-key models.chat.complete.deepseek.mpp \ --json ``` ## Text Analysis Example: Recommend Before Execute `text.analyze.diffbot-nl.mpp` is mapped and recommendable through Diffbot NL, but it is not live for execution yet. May 5, 2026 direct wrapper checks returned HTTP 429 before payment, so use CLI recommend and route context only until `canExecuteNow` is true and paid smoke evidence exists. ```bash npx agentrouter capabilities list text npx agentrouter capabilities contract text analyze npx agentrouter routes context text.analyze.diffbot-nl.mpp --json npx agentrouter recommend text analyze \ --input '{"provider":"diffbot-nl","content":"AgentRouter routes text analysis through Diffbot NL.","fields":"entities,sentiment,language","optimizationPreferences":["quality"]}' \ --json ``` ## Web And Enrichment Example: Pin Diffbot Routes Diffbot web extraction and Diffbot KG enrichment are live after the May 5, 2026 route-by-route retest. Inspect route context first, then pin the route when the operator wants that concrete Diffbot path. ```bash npx agentrouter routes context web.extract.diffbot.mpp --json npx agentrouter routes context enrichment.people.enrich.diffbot.mpp --json npx agentrouter routes context enrichment.company.enrich.diffbot.mpp --json npx agentrouter execute web extract \ --input '{"url":"https://www.example.com/article"}' \ --route-key web.extract.diffbot.mpp \ --json npx agentrouter execute enrichment people-enrich \ --input '{"fullName":"Sam Altman","companyName":"OpenAI"}' \ --route-key enrichment.people.enrich.diffbot.mpp \ --json npx agentrouter execute enrichment company-enrich \ --input '{"companyName":"OpenAI","domain":"openai.com"}' \ --route-key enrichment.company.enrich.diffbot.mpp \ --json ``` ## Travel Example: Pin FlightAPI Airport Operations Inspect the route context first: ```bash npx agentrouter routes context travel.airport.operations.flightapi.mpp --json ``` Then execute the live FlightAPI route explicitly: ```bash npx agentrouter execute travel airport-operations \ --input '{"iataCode":"JFK","mode":"departures","limit":1}' \ --route-key travel.airport.operations.flightapi.mpp \ --provider flightapi \ --json ``` FlightAPI airport operations passed a May 8, 2026 production smoke after the backend gate was removed. If a future wrapper error appears, treat it as route-test evidence to reconcile against the live catalog rather than as a static docs rule. ## When To Use CLI vs Other Surfaces Use [SDK](/integrations/sdk) when you are building direct application integrations in code. Use [SKILL.md](/integrations/skills) when another coding agent should read instructions and make HTTP calls itself. Use [MCP](/integrations/mcp) when the runtime is MCP-compatible and you want hosted tools instead of shell commands.