AIbridge CLI — Multi-provider AI from your terminal

Getting started

Available with the AIbridge source package

AIbridge CLI is not yet published as a public npm package. Until then, run it directly from the source checkout — the commands below always reflect what actually works today.

source package

$ npm install $ npm link $ aibridge doctor

// The public npm installation command will be added when the package is published.

Providers

Bring your own key. AIbridge doesn't issue one.

AIbridge doesn't provide or require a universal API key of its own. You use your own key for each provider you want to talk to — the CLI calls that provider directly, with your key.

Claude

claude · Anthropic

ChatGPT

gpt · OpenAI

Gemini

gemini · Google

Grok

grok · xAI

DeepSeek

deepseek · DeepSeek

Core workflow

Ask → Compare → Handoff → Workflow

Four ways to use one or more AI providers from the same CLI, all built on the same request/response layer AIbridge's web app uses.

01

Ask

02

Compare

03

Handoff

04

Workflow

Ask — query a single provider

ask

$ aibridge ask \ "Explain this function" \ --provider claude

Compare — run several providers in parallel

compare

$ aibridge compare \ "Review this architecture" \ --providers claude,gpt,gemini

Handoff — pass one provider's answer to another

handoff

$ aibridge handoff \ "Design this feature" \ --from claude \ --to gpt \ --instruction "Check security and edge cases"

Workflow — run a declarative multi-step file

workflow run

$ aibridge workflow run \ workflows/examples/design-and-review.json \ "Design a multi-tenant SaaS database"

Reference

Command reference

Every command AIbridge CLI supports today. Nothing here is aspirational — this mirrors docs/cli.md and each command's own --help output.

setupConfigure providers & preferences›

Description

Interactive walkthrough that explains, before asking anything, where each API key will (or won't) be stored. Never requires an AIbridge account.

Syntax

aibridge setup [--non-interactive]

Exit codes

0 success

Example

aibridge setup

providersList providers & configuration status›

Description

Shows which of the five supported providers are configured (an API key is resolvable) and where the key came from — never the key itself.

Syntax

aibridge providers [--format human|json]

Exit codes

0 success

Example

aibridge providers --json

modelsShow configured model per provider›

Description

Shows each provider's default model, and any override set via config set models.<id>.

Syntax

aibridge models [--format human|json]

Exit codes

0 success

Example

aibridge models

askQuery a single AI›

Description

Sends a single prompt to one provider. Prompt can come from an argument, piped stdin, or --file.

Syntax

aibridge ask "prompt" --provider <id> [--model <name>] [--max-tokens <n>]
  [--retries <n>] [--no-retry] [--retry-base-ms <n>]
  [--session <id>] [--no-save] [--format human|json]

Main options

--provider claude|gpt|gemini|grok|deepseek
--max-tokens integer, 1–8192 (default 1024)
--retries 0–5 (default 2), --no-retry, --retry-base-ms 100–10000 (default 500)
--file, --session, --no-save

Exit codes

0 success
2 invalid arguments
3 provider not configured
4 authentication error
5 rate limited
6 network/timeout

Examples

aibridge ask "Explain this error" --provider gpt
cat server.js | aibridge ask "Review this code" --provider claude

compareQuery multiple providers in parallel›

Description

Runs the same prompt against several providers concurrently. One provider failing never blocks the others.

Syntax

aibridge compare "prompt" --providers <id1,id2,...> [--concurrency <n>]
  [--timeout <ms>] [--max-tokens <n>] [--retries <n>] [--no-retry] [--format human|json]

Exit codes

0 at least one provider succeeded
1 all providers failed
2 invalid arguments

Each provider retries independently — one provider's backoff never delays another.

Example

aibridge compare "Review this architecture" --providers claude,gpt,gemini

handoffPass a response from one provider to another›

Description

Provider A answers first; provider B then receives your instruction plus provider A's (handoff-stripped) response as context.

Syntax

aibridge handoff "prompt" --from <id> --to <id> [--instruction "..."]
  [--max-tokens <n>] [--retries <n>] [--no-retry] [--format human|json]

Exit codes

0 success
2 invalid arguments
3/4/5/6 provider errors

The two stages retry independently — if the first provider succeeds and the second fails temporarily, only the second is retried; the first is never called again.

Example

aibridge handoff "Design this feature" --from claude --to gpt --instruction "Check security and edge cases"

workflow runRun a declarative multi-step workflow file›

Description

Validates a JSON workflow file, then runs its steps in order. success:true only if every step actually succeeded.

Syntax

aibridge workflow run <file.json> ["input"] [--file <path>] [--max-tokens <n>]
  [--retries <n>] [--no-retry] [--format human|json]

Exit codes

0 every step succeeded
2 invalid arguments / missing required input
7 invalid workflow file
3/4/5/6/1 depending on which step failed (see docs/cli-workflows.md)

Each step retries independently; a step that already succeeded is never re-run because a later step needed a retry.

Example

aibridge workflow run workflows/examples/design-and-review.json "Design a multi-tenant SaaS database"

sessions listList saved local sessions›

Syntax

aibridge sessions list [--format human|json]

Exit codes

0 success

Example

aibridge sessions list

sessions showShow a session's full content›

Syntax

aibridge sessions show <id>

Exit codes

0 success
2 unknown id

Example

aibridge sessions show 3f1c2a90

sessions deleteDelete one saved session›

Syntax

aibridge sessions delete <id>

Exit codes

0 success (even if the id didn't exist)
2 missing id argument

Example

aibridge sessions delete 3f1c2a90

sessions clearDelete all saved sessions›

Syntax

aibridge sessions clear

Exit codes

0 success

Example

aibridge sessions clear

config showShow current local configuration›

Syntax

aibridge config show

Exit codes

0 success

Example

aibridge config show

config setSet a non-secret config value›

Description

Refuses any key that looks like a secret (matching /key|secret|token|password|credential/i) — API keys never go through this command.

Syntax

aibridge config set <key> <value>

Exit codes

0 success
2 missing arguments or secret-looking key

Example

aibridge config set defaultProvider gpt

config resetReset config to defaults›

Syntax

aibridge config reset

Exit codes

0 success

Example

aibridge config reset

doctorDiagnose the local installation›

Description

Checks Node version, config/session directory permissions, config file health, keychain availability, and which providers are configured — never a network call unless --network is passed.

Syntax

aibridge doctor [--format human|json]

Exit codes

0 all checks passed
1 a check failed

Example

aibridge doctor

doctor --networkAlso check provider reachability›

Description

Adds a bare, unauthenticated HTTPS reachability check per configured provider. Never a paid or authenticated completion call — with or without this flag.

Syntax

aibridge doctor --network

Exit codes

0 all checks passed
1 a check failed

Example

aibridge doctor --network

Input

Prompts can come from an argument, stdin, or a file

Precedence: --file > argument + piped stdin (argument becomes the instruction, stdin the content) > stdin alone > argument alone. No input in any form → a readable error, never an empty prompt sent to a provider.

argument

$ aibridge ask "Explain this error" --provider gpt

stdin

$ cat server.js | aibridge ask \ "Review this code" \ --provider claude

--file

$ aibridge ask \ --file prompt.txt \ --provider gemini

Local sessions

Every conversation stays on your machine

✓Sessions are saved locally, as plain JSON files under ~/.aibridge/sessions/
✓Continue a previous session with --session <id>
✓Skip saving entirely with --no-save
✓List or delete sessions with aibridge sessions
✓API keys never end up in a session file — never

list

$ aibridge sessions list

continue

$ aibridge ask \ "Continue the analysis" \ --provider gpt \ --session <session-id>

Declarative workflows

One JSON file, several steps, no code execution

A workflow is a small, versioned JSON document. Each step can reference the workflow's input, or the output of a step that already ran.

design-and-review.json

{ "version": 1, "name": "design-and-review", "steps": [ { "id": "design", "provider": "claude", "prompt": "Design a solution for: {{input}}" }, { "id": "review", "provider": "gpt", "prompt": "Review this solution:\n{{steps.design.output}}" } ] }

// same shape as workflows/examples/design-and-review.json, shown here with simplified prompt text

✓{{input}} — the input you passed to the workflow (argument, stdin, or --file)
✓{{steps.<id>.output}} — the output of a step that already ran
✓The whole file is validated before any provider is called — a bad reference never reaches a real request
✓A step referencing a step that hasn't run yet (a forward reference) is rejected up front, as invalid
✓If a step fails, any later step that depends on its output is skipped, not run with a missing value

Automation

Structured JSON output for scripts and pipelines

ask --format json

$ aibridge ask \ "Summarize this file" \ --provider gpt \ --format json

The response includes success, provider, model, response, usage, finishReason, truncated, attempts, retried and durationMs. For workflow run, it also includes summary.total, summary.succeeded, summary.failed and summary.skipped — counting steps, not retry attempts.

✓success: true means the request (or every step, for a workflow) completed successfully.
✓If truncated: true, the content can be incomplete — even when success: true.

Security

Your keys stay under your control

✓Environment variables are the first place the CLI looks for a key
✓macOS Keychain is supported as a second option, when you opt in during aibridge setup
✓Otherwise, a masked prompt asks for the key for the current session only — never written to disk
✓No API key is ever written to the config file
✓No API key is ever written to a session file
✓No API key is ever printed to stdout or stderr, in any command or output format
✓No AIbridge account is required to use the CLI
✓Every request goes directly from your machine to the provider you chose

recommended shell pattern

$ read -s "OPENAI_API_KEY?OpenAI API key: " $ echo $ export OPENAI_API_KEY

Output limits

Truncated responses are never silent

✓Default output limit: 1024 tokens
✓Supported range: 1–8192, via --max-tokens
✓A visible warning appears when a provider hits the limit
✓finishReason and truncated are always available in JSON output

--max-tokens

$ aibridge ask \ "Write a detailed technical plan" \ --provider claude \ --max-tokens 4096

Reliability

Automatic retries for temporary errors

✓Rate limits, 5xx server errors, and transient network/timeout failures are retried automatically — not invalid arguments, auth errors, or unconfigured providers
✓Default: 2 retries (up to 3 attempts total), with capped exponential backoff
✓Respects a provider's Retry-After header when present, still capped for safety
✓Tune with --retries <0-5> and --retry-base-ms, or disable entirely with --no-retry
✓In rare cases a retried request may have been processed before the response was lost — meaning a possible extra generation or extra token usage; use --no-retry if that risk matters to you

--no-retry

$ aibridge ask \ "Explain this error" \ --provider gpt \ --no-retry

Troubleshooting

Common issues

Provider not configured›

Exit code 3. Set the relevant environment variable, or run aibridge setup. Check current status with aibridge providers.

Key not recognized (authentication error)›

Exit code 4. The provider rejected the key — check for a typo, an expired key, or a key issued for a different account/project.

Timeout or network error›

Exit code 6. Check your connection, or increase the limit with --timeout <ms>.

Truncated response›

Look for the ⚠ warning, or check truncated: true in JSON output. Raise the limit with --max-tokens (1–8192).

Workflow with no input›

Exit code 2. If any step references {{input}}, pass one as an argument, via stdin, or with --file.

Invalid workflow file›

Exit code 7. The error message names the exact problem (bad schema, forward reference, unknown provider) — no step ever runs for an invalid file.

"aibridge: command not found"›

Re-run npm link from the source checkout, then confirm it's on your PATH:

npm link

which aibridge

Use multiple AI models directly from your terminal.

Available with the AIbridge source package

Bring your own key. AIbridge doesn't issue one.

Ask → Compare → Handoff → Workflow

Ask — query a single provider

Compare — run several providers in parallel

Handoff — pass one provider's answer to another

Workflow — run a declarative multi-step file

Command reference

Description

Syntax

Exit codes

Example

Description

Syntax

Exit codes

Example

Description

Syntax

Exit codes

Example

Description

Syntax

Main options

Exit codes

Examples

Description

Syntax

Exit codes

Example

Description

Syntax

Exit codes

Example

Description

Syntax

Exit codes

Example

Syntax

Exit codes

Example

Syntax

Exit codes

Example

Syntax

Exit codes

Example

Syntax

Exit codes

Example

Syntax

Exit codes

Example

Description

Syntax

Exit codes

Example

Syntax

Exit codes

Example

Description

Syntax

Exit codes

Example

Description

Syntax

Exit codes

Example

Prompts can come from an argument, stdin, or a file

Every conversation stays on your machine

One JSON file, several steps, no code execution

Structured JSON output for scripts and pipelines

Your keys stay under your control

Truncated responses are never silent

Automatic retries for temporary errors

Common issues

One interface. Multiple AI providers.