IQ CLI

The IQ CLI is the local terminal for the gateway. Three subcommands:

iq prompt "..." -- single-prompt round-trip with a routing telemetry box (tier, model, focus mode, cache, latency split, cost).
iq batch prompts.txt -- run a prompt file end-to-end with a per-prompt line and an aggregate table at the close.
iq generate-prompts -- emit a synthetic prompt file at the requested difficulty mix.

Install

Download the signed binary for your platform from the release assets shared with your account. Pick the latest release and grab the asset matching your OS and architecture. Each release ships a checksums file and a detached signature. Verify the download against the published checksum, then make it executable and put it on your PATH:

# After verifying the checksum:
chmod +x iq
sudo mv iq /usr/local/bin/iq

On Windows, download the .exe asset from the same release, verify its checksum, and move it onto your PATH.

Sign in

iq login

iq login opens the dashboard's CLI access tokens page in your default browser. Issue a token under Settings → CLI access tokens, paste it back at the prompt. The CLI stores the token at ~/.config/iq-routing/credentials.toml (%APPDATA%\iq-routing\credentials.toml on Windows) at mode 0600.

The token has the prefix iqp_. SDK keys (prefix iq_) do not work with the CLI; the gateway routes on the prefix to the personal-access-tokens table for verification, scoped narrower than the org-level SDK keys.

Single-prompt mode

$ iq prompt "Summarise the last quarter's earnings call in three bullets"

Routing
  Tier:           medium
  Complexity:     6.2 / 10
  Chosen model:   anthropic/claude-haiku-4-5
  Focus mode:     balanced (no bias)
  Cache:          miss (new prompt)

Latency
  Total:          1842 ms
  Gateway-side:    34 ms
  LLM-side:      1808 ms

Tokens
  Prompt:           17
  Completion:      142

Cost
  This request:   $0.000482

Response
─────────────────────────────────────────────────────────────────────────
- Revenue grew 12 percent YoY, driven by the AI gateway segment.
- Margins compressed 80 bps as inference costs outpaced price increases.
- Guidance trims FY26 EPS by 3 percent to reflect the launch ramp.
─────────────────────────────────────────────────────────────────────────

Flags:

--raw -- print only the response body. No telemetry box. Useful for piping into another tool.
--json -- print the full response as JSON with the telemetry inlined under x_iq_routing.
--model -- pin a model alias (default, cheap, frontier) or a concrete provider/model string.
--timeout -- request timeout in seconds. Default 60.

Batch mode

$ iq batch prompts.txt --concurrency=4 --out=results.jsonl

Reading prompts.txt: 20 prompts loaded
Concurrency: 4

  1/20  ✓  simple    haiku-4-5    cache-miss   0.84s   $0.00012
  2/20  ✓  medium    haiku-4-5    cache-miss   1.92s   $0.00048
  3/20  ✓  simple    haiku-4-5    cache-hit    0.04s   $0.00000
  ...
 20/20  ✓  complex   sonnet-4-6   cache-miss   3.41s   $0.00284

Aggregate
  Total prompts:        20
  Successes:            20
  Failures:              0
  Cache hit rate:       35%
  Tier mix:             simple 8 · medium 9 · complex 3
  Latency p50:        1.42s
  Latency p99:        4.18s
  Total spend:        $0.0341
  Avg cost / prompt:  $0.00171

  Wrote results.jsonl with 20 rows.

Flags:

--concurrency=N -- in-flight requests. Defaults to 4. Caps at 16 (per-org rate-limit ceiling); higher values clamp with a stderr warning.
--out=results.jsonl -- write one JSONL row per prompt with the full response body and the telemetry inlined under x_iq_routing.
--model, --timeout -- same semantics as iq prompt.

The exit code goes non-zero when at least one prompt fails (any 5xx, timeout, or transport error). Failed prompts do not abort the run; the aggregate reports successes and failures together.

Prompt-file format

One prompt per line. Blank lines and #-prefixed lines ignored.

# easy
What is the capital of France?
Translate "good morning" to Spanish.

# medium
Given this CSV row, output a JSON object with the columns as keys: 1,Alice,30

Prompt generator

iq generate-prompts --difficulty=mixed --count=20 --out=prompts.txt

Difficulty bands:

easy -- single-sentence factual lookups, single-step instructions. Target tier simple.
medium -- multi-step reasoning, structured output, short code snippets. Target tier medium.
hard -- long-context, ambiguous instructions, cross-domain synthesis. Target tier complex.
mixed -- 40% easy, 45% medium, 15% hard. Matches the observed production traffic distribution.

Counts cap at 1000 per file. The generator does not call the gateway; it is a pure offline emitter.

Tokens, scopes, and revoke

The CLI authenticates with a personal access token issued from Settings → CLI access tokens. Default scopes:

read:routing -- view routing decisions.
write:prompt -- send prompts via the CLI.

Wider scopes (read:audit, write:settings) are opt-in at issue time. Tokens display the plaintext exactly once at issue. The dashboard shows only the prefix on subsequent reads.

iq logout removes the local credentials file. To revoke server-side, open Settings → CLI access tokens and click Revoke on the token row.

Bundle mode

The standalone gateway bundle ships the CLI as part of the single-binary install. iq-gateway prompt "..." posts to the local gateway at http://localhost:8000; the same telemetry box renders.

Bundle install: download the iq-gateway bundle asset from the release assets shared with your account, verify its checksum, and put it on your PATH.

iq-gateway serve            # boots the gateway + opens the dashboard
iq-gateway prompt "..."     # uses the local gateway

The bundle's analytics surfaces (board deck, judge metrics, decomposed cache shadow) render a Limited mode banner because they need Postgres-only SQL; the routing path runs end-to-end on SQLite.

Troubleshooting

Token in {path} does not start with iqp_ -- you copied an SDK key (iq_*) by mistake. Issue a personal access token from the dashboard.
Credentials file is group- or world-readable -- POSIX safety check. Run chmod 0600 ~/.config/iq-routing/credentials.toml.
Gateway returned 401 -- the token expired or was revoked. Run iq login to reissue.
Telemetry box shows telemetry unavailable -- your gateway is too old or IQ_TELEMETRY_HEADER=disabled is set. Update the gateway image or unset the env.