AIVAX CLI: operate your account from the terminal

Operating an AI platform from a terminal used to mean a folder of curl scripts and a browser tab. The scripts carried the endpoint paths, the auth header, and whatever request body someone pasted in six months ago. The dashboard held the rest: rotating a key, checking a balance, reading a conversation log. Between the two, nothing was reproducible — the script that worked on Monday failed on Tuesday because the body was edited by hand, and the dashboard click left no trace in git.

The AIVAX CLI collapses that split into one binary. It covers the same products as the API — AI gateways, RAG collections, chat clients, Batch, Agentic Tests, web search, OCR, generations, conversations, skills, logs, and account settings — so the terminal becomes the single place where an account is inspected and changed. The CLI documentation states the intended division directly: the CLI for people and agents working interactively or from scripts, the API or an SDK for application code serving end users.

Install and link an account in two commands

The CLI is published on npm as @aivax/cli under the MIT license, and it requires Node.js 22.19 or newer:

npm install -g @aivax/cli
aivax auth login

The same package installs with pnpm add -g @aivax/cli or bun install -g @aivax/cli, and npx @aivax/cli <command> runs it without a global install.

aivax auth login prompts for a login key and a 2FA code, or links an existing API key with --api-key sk-aiv-acc... --profile-name agente. Several named profiles coexist on one device, and any command accepts --profile <name>. The access key itself is stored in the operating system credential store through @napi-rs/keyring — Windows Credential Manager, macOS Keychain, or a Secret Service provider such as GNOME Keyring or KWallet on Linux — so only profile metadata lands in a plain config file. Scripts and CI can skip profiles entirely with the AIVAX_API_KEY environment variable.

What the terminal gains

The command surface mirrors the API, which means the operations that used to live in dashboard clicks become scripted and reviewable:

aivax gateways patch --id <GATEWAY_ID> -d '{"instructions": "..."}'
aivax web search -q "AI regulation news" --country US
aivax rag search --collection <COLLECTION_ID> -q "refund policy" -k 20 --reranker rrf
aivax ocr document manual.pdf --format jsonl -o manual.jsonl
aivax gateways chat -m my-gateway "Summarize this contract" -f contract.pdf --stream
aivax batch jobs create -w <workflow> -t "October batch"
aivax batch jobs export -w <workflow> -j <job> -o results.jsonl
aivax generate speech -m <model> -t @script.txt -o narration.mp3
aivax tests evaluate -m checkout-gateway -g @objective.txt --max-turns 6
aivax api get /api/v1/notifications/unread/count

Two conventions matter for daily use. Request bodies go through -d '<json>', -d @file.json, or stdin, with field flags merged over the body, so a gateway edit is a diff in git instead of a form. And long-running inference — chat completions, generations, query, answer, web fetches, chat-client prompts — routes to direct.inference.aivax.net with no proxy timeout and a 20-minute client timeout, so a long generation does not die at a gateway's idle cutoff.

The OCR path deserves its own mention. aivax ocr document transcribes a PDF page by page locally — recompressing large embedded images, splitting pages into standalone PDFs, grouping them into chunked requests — and with --format jsonl emits segmented, RAG-ready lines with per-page metadata. That output feeds directly into the ingestion-quality checks we described in how to check PDF ingestion quality before embedding for RAG, and the same JSONL streams into a collection through aivax rag import over a single WebSocket import.

Built for agents first, readable on demand

Responses are requested with an X-Response-Truncating: agent-optimized header by default, which returns compact TOON text rather than full JSON. That is a deliberate trade: the output is dense and cheap for a model to consume, and less pleasant for a human to eyeball. Pass --verbose when you want the full JSON, and -o <file> on export and download commands when you want a file instead of stdout.

This default exists because a growing share of CLI sessions have a model on one end. The AIVAX platform itself can walk an agent through setup — install the package, link a profile with aivax auth login --api-key ... --profile-name ..., then verify with aivax auth whoami and aivax analytics balance — so a coding harness can be pointed at the CLI and reach the whole account without a bespoke MCP integration for every product. That matters as tool surfaces grow; we wrote in why too many MCP tool definitions waste tokens about the cost of exposing dozens of narrow tools where one capable command line would do. The same reasoning applies to batch operations: the CLI's batch jobs export pairs naturally with the recovery patterns from expired batch jobs and retrying only what failed.

Boundaries to know before adopting it

The CLI needs Node.js 22.19 or newer and ships as plain JavaScript with no build step. Keys live in the OS credential store, which is the right default on a developer machine but assumes that store is available — on Linux, a Secret Service provider must be running; on a headless server, set AIVAX_API_KEY instead. Destructive commands (delete, reset, clear, roll-salt) ask for confirmation unless --yes is passed, and non-interactive sessions require it, so an unattended script must decide explicitly. Exit codes are stable — 0 success, 1 API or runtime error, 2 usage error — which is what makes the CLI composable in shell pipelines.

For everything the dedicated commands do not cover, aivax api <method> <path> calls any endpoint raw, and aivax docs reference <Endpoint> prints the API reference without leaving the terminal. The full command surface is documented in the CLI guide.