@rateapi/cli

Use RateAPI's source-proven US credit-union rate data directly or through a terminal-capable agent. Requires Node.js 20.19 or newer.

npm install --global @rateapi/cli
rateapi

The CLI is a thin client and installer. RateAPI's REST API, MCP server, capability catalog, and evidence rules remain authoritative. It never maintains a local rate corpus or bulk-exports the dataset.

Shop from the terminal

rateapi
rateapi auto
rateapi mortgage
rateapi refinance
rateapi deposit

Running rateapi opens a product chooser. The four shortcuts go directly to a guided workflow, ask only for the facts needed for that comparison, run one live search after approval, and format the evidence-backed matches for a person. rateapi guide auto remains a compatibility alias for the auto workflow in an interactive terminal; it no longer stops at an instruction echo.

On the first live search, the CLI asks for an email and approval to call POST /keys. RateAPI creates a Free API key and the CLI stores that response at ~/.config/rateapi/credentials.json. On POSIX systems the directory is mode 0700 and the credential file is mode 0600; on Windows it lives under the current user profile. The secret is never printed. Until that write succeeds, the CLI retains only a protected request UUID so an ambiguous timeout or process restart can recover the same server-generated key without creating another one. The server keeps that recovery response replayable for 24 hours, then queues it for hourly deletion. The UUID is not an API credential and cannot authorize data requests, but it is a temporary recovery capability: do not log or share it. The CLI stores it in a mode-0600 file and removes it after the API key is safely stored. If RATEAPI_API_KEY or a stored credential already exists, the CLI reuses it and does not request a new key.

Human example

$ rateapi auto
State (2 letters): NC
ZIP for local context (optional): 28202
Amount to finance ($): 35000
Term in months [60]:
Vehicle condition
  1. New
  2. Used
Choose a number: 1

The CLI summarizes the search before any live call, separately asks before key creation/storage and before spending one request from quota, and prints only offers carrying the credit union, source-page evidence, and observation time. A request does not create a charge. Published pricing is not approval or guaranteed availability.

All workflow inputs are also flags, so a script or terminal-capable agent can provide known facts without answering prompts:

rateapi auto --state NC --zip 28202 --amount 35000 --term 60 --condition new
rateapi deposit --state NC --product cd --term 12

For a retry-safe non-interactive POST, generate one UUID and reuse it with the same inputs:

RATEAPI_REQUEST_ID="${RATEAPI_REQUEST_ID:-$(node -e 'console.log(crypto.randomUUID())')}"
rateapi auto --state NC --zip 28202 --amount 35000 --term 60 --condition new \
  --idempotency-key "$RATEAPI_REQUEST_ID"

The CLI also derives a stable decision request_id from that UUID, so an ambiguous network retry has the same request body and does not spend a second quota unit.

Use it from a terminal-capable agent

The CLI is the default RateAPI entry point whenever an agent can run shell commands. Run rateapi agent --json to print the agent-specific operating contract. Agents use --json for stable envelopes and the low-level commands below when they need direct control over a capability:

rateapi agent --json
rateapi capabilities --json
rateapi schema rate-shopping --json
rateapi run rate-shopping --input @scenario.json --confirm-request --idempotency-key "$RATEAPI_REQUEST_ID" --json

Example scenario.json:

{
  "decision_type": "financing",
  "context": {
    "request_id": "cli_example_001",
    "geo": { "state": "NC" }
  },
  "product_request": {
    "product_type": "mortgage",
    "intent": "purchase",
    "amount": 420000,
    "term_months": 360
  }
}

Personal scenarios should be passed through a file or stdin (--input @-) instead of exposed in shell arguments. rateapi install --agent codex --dry-run previews durable agent setup without changing files.

Add the remote MCP server only when the host has no shell or the human explicitly wants persistent native tool discovery or rich in-chat widgets. Applications and backends should call the REST API directly instead of spawning the CLI.

To preview the CLI without installing it globally, run:

npx -y @rateapi/cli@latest welcome

That one-off npx process does not create a persistent rateapi command.

rateapi install is a dry run unless you add --apply. It can install the versioned RateAPI skill for Codex, Claude Code, OpenClaw, or another skill-compatible agent. Only when the human separately asks for persistent MCP and approves the config change, add --mcp; for Codex that can append a remote MCP entry to ~/.codex/config.toml. The entry refers to RATEAPI_API_KEY by name and never writes the key into TOML. CLI and MCP credentials are separate: the credential file created by rateapi login authenticates CLI commands only. Codex MCP setup requires RATEAPI_API_KEY in the environment that launches Codex.

rateapi login performs the same first-time key setup without starting a product search. If a credential already exists, it creates nothing. In automation, pass the email through stdin and add --confirm-key only after the user has approved API-key creation and local storage:

printf '%s\n' '{"email":"[email protected]"}' | rateapi login --input @- --confirm-key --json

The registration endpoint generates the secret; the CLI never generates an API credential. The CLI never prints the response key and writes it directly to the protected credential file. Subsequent authenticated API calls send the secret in the X-API-Key header over HTTPS. Existing credentials always win, concurrent first-run processes cannot replace one another, and a byte-identical retry reuses the pending request UUID to recover the same response for up to 24 hours.

Existing Free, Pro, or Enterprise users can persist a key without placing it in shell history:

rateapi key import --input @- --confirm-key

Then type the JSON below and press Ctrl-D:

{"api_key":"rk_your_existing_key"}

The CLI never prints the imported secret. You can instead keep using RATEAPI_API_KEY without persisting it.

The keyless rateapi demo command is a synthetic contract example. It is deliberately marked as non-live and must never be quoted as a current offer. Run rateapi doctor to distinguish that demo from authenticated live access.

Every live rate must retain its institution, source evidence, and as_of. Published pricing is not approval, unknown eligibility is not rejection, and benchmarks are credit-union medians—not a national average.

Release

The package has no install-time lifecycle script and publishes only dist/, this README, and the MIT license. GitHub Actions publishes with npm trusted publishing from .github/workflows/publish-cli.yml; the npm package's trusted publisher must name the holdequity/rateapi repository and that workflow file. The publish job uses GitHub OIDC rather than a stored npm token and emits npm provenance automatically.