v0.2.1

AI CLI Gateway v0.2.1

v0.2.1 adds npm as a distribution channel for the existing native AI CLI Gateway. It does not introduce a new JavaScript API or a new gateway runtime.

npm installation

Install the exact release with Node.js >=22.14.0:

npm install --global ai-cli-gateway@0.2.1
ai-cli-gateway version

The launcher and native packages have no lifecycle scripts. npm selects one compatible native optional package during normal dependency resolution; installation does not download an executable through a lifecycle hook, and first execution performs no application-owned network download.

Supported targets

The launcher supports exactly these five npm targets:

npm target	Native package	npm host constraint
darwin-x64	ai-cli-gateway-darwin-x64	darwin / x64
darwin-arm64	ai-cli-gateway-darwin-arm64	darwin / arm64
linux-x64	ai-cli-gateway-linux-x64	linux / x64
linux-arm64	ai-cli-gateway-linux-arm64	linux / arm64
win32-x64	ai-cli-gateway-win32-x64	win32 / x64

Unsupported hosts fail closed. A missing, linked, corrupt, or version-mismatched native package also fails closed instead of searching PATH for another binary.

Supply-chain equivalence and provenance

Every npm native executable is byte-for-byte identical to the executable in its matching immutable GitHub Release archive. The release workflow verifies the published asset digests, reproduces all five archives, compares their SHA-256 values, and only then stages and inspects the npm tarballs.

All six public npm packages carry npm provenance. The five archives, the SPDX SBOM, and SHA256SUMS have separate GitHub build-provenance attestations tied to the v0.2.1 tag and the release workflow. npm provenance covers package publication; GitHub provenance and checksums cover the release assets from which the native packages are derived.

Unchanged gateway runtime

The native Go gateway remains the runtime. CLI arguments, standard streams, numeric exit status, and supported termination signals pass through the dependency-free Node launcher. Guided init, configuration, provider ownership, loopback HTTP endpoints, request limits, process containment, and the documented Responses-compatible subset are unchanged from v0.2.0.

Downloads and verification

The release contains five platform archives:

• ai-cli-gateway_0.2.1_linux_amd64.tar.gz
• ai-cli-gateway_0.2.1_linux_arm64.tar.gz
• ai-cli-gateway_0.2.1_darwin_amd64.tar.gz
• ai-cli-gateway_0.2.1_darwin_arm64.tar.gz
• ai-cli-gateway_0.2.1_windows_amd64.zip

SHA256SUMS covers those archives and the ai-cli-gateway_0.2.1_sbom.spdx.json SPDX SBOM. Verify the selected archive checksum and its GitHub attestation before extraction when using the manual installation path.

Use Getting Started for npm and manual installation, updates, uninstall, recovery, and a first request. Use the API and Operations Reference for the exact runtime contracts, and the Security Policy for private vulnerability reporting.

v0.2.0

AI CLI Gateway v0.2.0

v0.2.0 adds guided init: a reviewed, two-command path from authenticated provider CLIs to a running local Gateway.

Guided setup

Run ai-cli-gateway init, then ai-cli-gateway serve. One guided session can configure multiple providers—Codex CLI, Claude Code, and Gemini CLI—and multiple model aliases. Discovery is advisory: you confirm executable paths, config homes, authentication profiles, and each alias/provider-model pair before anything is written.

Init performs a safe merge, preserving unselected configuration. Name collisions require an explicit replacement choice, and --dry-run validates and previews the redacted semantic diff without creating or changing files. With the default Gateway authentication choice, init creates a private gateway.key and stores its path through api_key_file rather than placing the key in the configuration.

The default configuration paths are:

• POSIX: ${XDG_CONFIG_HOME:-$HOME/.config}/ai-cli-gateway/config.toml
• Windows: %LOCALAPPDATA%\AI CLI Gateway\config\config.toml

After a confirmed write, init runs post-write Doctor checks and prints stable next steps. A ready configuration, a successful dry run, or declining final confirmation uses exit 0. A safe-write failure or a stored configuration that is not Doctor-ready uses exit 1. Invalid or incomplete input and unapproved collisions use exit 2. Cancellation uses exit 130; if cancellation happens during Doctor, the confirmed configuration remains stored.

Huh is a local terminal UI only. During setup, init sends no provider request, never installs a CLI, never runs provider login, never launches inference, never starts the Gateway listener, and never guesses a model. Provider credentials remain owned by provider tooling: the Gateway records only the confirmed authentication shape, not provider credential values. Gemini setup does not offer cached OAuth.

Compatibility

v0.1 configuration files remain compatible. Existing providers, models, and comments outside selected replacements are preserved, and existing environment-auth configurations using api_key_env remain supported. Unrecognized fields still fail strict configuration validation. You can keep using strict --non-interactive flags for automation or the documented manual configuration path.

Downloads and verification

The release contains five platform archives:

• ai-cli-gateway_0.2.0_linux_amd64.tar.gz
• ai-cli-gateway_0.2.0_linux_arm64.tar.gz
• ai-cli-gateway_0.2.0_darwin_amd64.tar.gz
• ai-cli-gateway_0.2.0_darwin_arm64.tar.gz
• ai-cli-gateway_0.2.0_windows_amd64.zip

SHA256SUMS covers every archive and ai-cli-gateway_0.2.0_sbom.spdx.json. GitHub build-provenance attestations are published separately for all seven downloadable assets.

Use Getting Started for installation and the first request, the API and Operations Reference for exact init, Doctor, and exit contracts, and the Security Policy for private vulnerability reporting.

v0.1.0

AI CLI Gateway v0.1.0

Build AI MVPs with the AI CLI access you already have.

AI CLI Gateway turns locally authenticated AI CLIs into an OpenAI Responses-compatible API. v0.1.0 is a focused, local/self-hosted Responses API-compatible subset for fast prototyping, demos, and product validation.

Why this exists

Your AI tools already work in the terminal. Your MVP expects an API. AI CLI Gateway bridges that gap locally: application code calls one loopback endpoint, while configured provider/model aliases route each request to Codex CLI, Claude Code, or Gemini CLI.

What you can build

• Vibe-coded AI-service MVPs with a familiar HTTP boundary.
• Product validation against final text or structured JSON output.
• Demos and hackathons that can switch configured CLI backends without rewriting the client.
• Local integration testing with OpenAI Python or JavaScript SDK request shapes.

Supported in v0.1.0

• POST /v1/responses for one completed, non-streaming response.
• GET /v1/models for configured model aliases.
• instructions, string input, model, text output, and strict JSON Schema output.
• Codex CLI, Claude Code, and Gemini CLI adapters behind a provider-neutral interface.
• doctor diagnostics for binary, version, capability, authentication-readiness, containment, and runtime checks.
• Per-provider concurrency limits, bounded queues and output, request timeouts and cancellation, and child process-tree cleanup.
• Stable API errors for unsupported parameters, provider failures, timeouts, malformed output, and schema mismatch.

Not in v0.1.0

• SSE streaming.
• Tool/function-call round trips.
• Stored conversations or gateway sessions.
• Web UI or external database.
• Complete OpenAI endpoint or SDK compatibility.

Unsupported request fields fail with an explicit 400 response instead of being silently ignored.

Authentication and data boundary

You install and authenticate each official CLI. AI CLI Gateway does not issue, extract, copy, or store provider login tokens. Prompts are sent to the selected CLI over stdin, never through a shell command string or prompt argument. Sensitive prompts, model output, credentials, and authentication contents are excluded from gateway logs.

The gateway and CLI credential boundary are local. The selected CLI may send request data to its upstream provider. Users remain responsible for their provider access and applicable terms.

Release integrity

v0.1.0 provides five platform archives, SHA256SUMS covering every archive and the SBOM, and one SPDX SBOM for the five shipped binaries. GitHub stores build-provenance attestations separately for all seven downloadable assets.

Get started

• Secure installation and first request
• API and operations reference
• OpenAI SDK example
• Security policy
• Contributing
• Full v0.1.0 changelog