CLI reference

Every routergrowth command: setup, keys, discover, inspect, run, runs, balance.

The routergrowth CLI mirrors the API one-to-one: same names, same JSON, printed as plain text with no colors and no interactive prompts, so agents can drive it directly.

npm install -g routergrowth

EACCES? Install per-user: npm install --prefix ~/.local routergrowth, then symlink ~/.local/node_modules/.bin/routergrowth into your PATH.

Commands

setup

routergrowth setup --client "my-agent"

Initializes local config and identifies the calling client (useful when several agents share a machine).

signup

routergrowth signup --email you@company.com --org "Acme"

Sandbox onboarding: creates an organization with $1 of promotional credit and saves the minted rg_test_ key locally. On production, mint keys in the dashboard instead and store them with keys add.

keys

routergrowth keys add -k rg_live_... -l main   # store a key under a label
routergrowth keys list                          # stored keys (labels, never raw keys)
routergrowth keys activate -l main              # switch the active key
routergrowth keys remove -l old                 # delete a stored key

Keys live in local config only; never commit them.

balance

routergrowth balance

Prints the wallet: balance, reserved, available. Same data as GET /v1/wallet.

discover

routergrowth discover -q "find a verified email for a person"
routergrowth discover -q "tiktok video comments" --kind endpoint --provider tikhub

Catalog search by job description; free. One ranked list of capabilities and raw provider endpoints, each with its kind, status, relevance score, price or cost model and health verdict, followed by the server's hints on what to do next. --kind and --provider narrow it.

endpoints

routergrowth endpoints -p dataforseo -q backlinks

Everything one provider serves raw, with a substring filter. Free.

inspect

routergrowth inspect -c contact.find
routergrowth inspect -p dataforseo -e /v3/serp/google/organic/live/advanced

The capability's contract: input schema, output fields, providers, exact prices, billing conditions, health. For a raw endpoint (-p and -e): the provider's own input spec, cost model, health, which capability wraps it, and a ready-to-paste run line. Run it before the first run of a capability or endpoint.

run

routergrowth run -c contact.find \
  -i '{"first_name":"Alex","last_name":"Rivera","company_domain":"example.com"}' \
  --max-cost 0.10
# returns a compact receipt immediately
routergrowth runs get -r <run_id> --wait 60 -o result.json

run submits immediately by default and returns a compact receipt with the run ID. This keeps provider latency out of the agent's request path. Add --wait, or poll with runs get -r <run_id> --wait 60. Write large results to a file with -o; the summary line still prints what was charged and which provider delivered.

A raw endpoint run addresses the provider directly:

routergrowth run -p dataforseo -e /v3/serp/google/organic/live/advanced \
  -i '{"keyword":"best crm","location_code":2840,"language_code":"en"}' \
  --max-cost 0.05 -o serp.json

There is no quote: the run settles on the provider's measured cost after the call, never above --max-cost.

runs

routergrowth runs                 # recent runs, newest first
routergrowth runs get -r run_... --wait 60 -o result.json

Same records as GET /v1/runs: status, provider, attempts, quoted and charged amounts.

history

routergrowth history alex.rivera@example.com          # every run that mentions this person: touches, results to reuse
routergrowth history example.com                      # a company: enrichments, people found there, anyone at it contacted
routergrowth history https://www.linkedin.com/in/alex-rivera
routergrowth history "Alex Rivera" --kind text
routergrowth history --file leads.txt                 # one identifier per line: seen / contacted / reusable, before a batch

Check it before enriching or messaging anyone. It is GET /v1/history over the run log, so it is exactly as complete as what went through RouterGrowth. Free.

events

routergrowth events                                              # everything still kept, oldest first
routergrowth events --types email.received,email.bounced         # only these event types
routergrowth events --since 2026-10-03T09:00:00Z                 # start from a time when there is no cursor yet
routergrowth events --cursor-file out/events-cursor.txt -o out/events.json   # only what is new since the last run

Replies, bounces, spam complaints, LinkedIn, Instagram and WhatsApp messages, new LinkedIn connections and dropped sessions across every inbox and connected account, in one call. --cursor-file reads the last event id from the file and writes the new one back, so a daily run returns only what came in since the previous one; --after EVT_ID does the same by hand. Same stream as GET /v1/events. Free. Needs CLI 0.6.0 or later.

guard

routergrowth guard                 # daily cap, per-run ceiling, today's spend
routergrowth guard --daily 25      # block runs once $25 is spent in a UTC day
routergrowth guard --per-run 1     # block any single run holding more than $1 (off by default)
routergrowth guard --per-run off
routergrowth guard --off

Ground rules for agents

• inspect before the first run of a capability or endpoint: its input schema is the source of truth, never guess inputs.
• Report costs when they matter to the user: they asked, they set a budget, or a multi-run job ends (the sum of billing.charged).
• Cap every call with --max-cost; on raw endpoints it is the only price control you have before the run.
• Prefer a capability over the raw endpoint it wraps (discover says which): normalized output, a quote, failover.
• Stop and ask before a batch that would exceed about $1.
• Never present sandbox mock output as real data.

Reading this as an agent? This page as markdown: /docs/cli/overview.md · every page: /docs/llms.txt