Integrations

CLI

Run AgentRouter from your terminal with the thin SDK-backed CLI

View as Markdown

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:

$npm install @agentrouter/agentrouter

Then run:

$npx agentrouter --help

If you only need a one-off command and do not want to add the package to a project yet:

$npx -p @agentrouter/agentrouter agentrouter domains list

Set Environment

$export AGENTIC_API_BASE_URL=https://api.agentrouter.to/api/agentic-api
$export AGENTIC_API_KEY=aak_...

Optional environment variables:

$export AGENTIC_API_SESSION_TOKEN=session_...
$export AGENTIC_API_USER_ID=agentic-local-user
$export AGENTIC_API_TIMEOUT_MS=20000
1

Inspect the catalog

$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
2

Recommend before execute

$npx agentrouter recommend email send \
>  --input '{"optimizationPreferences":["cost","quality"]}' \
>  --json
3

Execute explicitly

Save a request body to send-email.json:

1{
2  "to": "maya@example.com",
3  "subject": "Hello from AgentRouter",
4  "html": "<p>Hello</p>"
5}

Then execute:

$npx agentrouter execute email send \
>  --input @send-email.json \
>  --provider resend \
>  --allow-fallback \
>  --json
4

Inspect wallet and usage

$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.

$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.

$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

agentrouter wallet
agentrouter usage [--limit 20]
agentrouter domains list|get
agentrouter capabilities list|get|routes|contract
agentrouter recommend <domain> <capability> --input <json|@file>
agentrouter execute <domain> <capability> --input <json|@file>
agentrouter route <domain> --input <json|@file>
agentrouter raw <method> <path>

Input Conventions

The CLI accepts request bodies in two forms:

Inline JSON:

$npx agentrouter recommend email send \
>  --input '{"optimizationPreferences":["cost"]}'

JSON file:

$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.

$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.

$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.

$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.

$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.

$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:

$npx agentrouter routes context travel.airport.operations.flightapi.mpp --json

Then execute the live FlightAPI route explicitly:

$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 when you are building direct application integrations in code.

Use SKILL.md when another coding agent should read instructions and make HTTP calls itself.

Use MCP when the runtime is MCP-compatible and you want hosted tools instead of shell commands.