agw-client-cli

Interactive npm/npx setup for Claude Code CLI and Codex CLI using an existing Agent Gateway virtual key.

This package is intentionally smaller than the Electron agw-client app:

• virtual-key only; it does not sign in with Google SSO
• Claude Code CLI and Codex CLI only; no Claude Cowork support
• no shell rc snippets, OTel config, MDM baggage headers, or helper session
• full replacement writes with one-time .egw-backup sibling backups

Install

npm install -g @tvps/agw-client-cli
agw-client-cli setup

Or run without installing:

npx @tvps/agw-client-cli setup

setup, switch, and uninstall require an interactive terminal.

Package Details

This package is published as @tvps/agw-client-cli (scoped under the @tvps organization). The scoped name is required when installing globally or running via npx.

Setup

agw-client-cli setup

The wizard asks for:

• gateway URL, for example https://gateway.example.com
• virtual key copied from the AGW Admin virtual-key screen
• targets to enable: Claude Code CLI, Codex CLI, or both
• provider/model choices fetched live from the gateway

Setup blocks if the selected target binary is missing from PATH. It then fetches Kiro and Codex model lists and sends tiny generation probes with the prompt Reply with OK. through all four paths:

• /kiro/anthropic/v1/messages
• /kiro/openai/v1/responses
• /codex/anthropic/v1/messages
• /codex/openai/v1/responses

Those probes verify that the key works through the gateway. They are real model requests, so they can consume upstream quota and create gateway audit rows.

Commands

agw-client-cli switch
agw-client-cli status
agw-client-cli models
agw-client-cli uninstall

switch interactively changes one target to Kiro, Codex, or official/direct mode. Official/direct mode restores the .egw-backup file if it exists; if no backup exists, it deletes the gateway-managed config so the upstream client can fall back to its normal official configuration. The stored virtual key is kept so you can switch back later.

status prints local config paths, binary status, and always runs the model list plus tiny generation probes. This is useful for diagnosis but can consume upstream quota.

models fetches both Kiro and Codex every time and prints grouped model lists for verbose, OpenAI, and Anthropic formats.

uninstall restores or deletes Claude and Codex configs, then deletes the CLI state file and stored virtual key.

Files

State is stored as plaintext JSON:

• macOS: ~/Library/Application Support/agw-client-cli/state.json
• Linux: ${XDG_CONFIG_HOME:-~/.config}/agw-client-cli/state.json
• Windows: %LOCALAPPDATA%\agw-client-cli\state.json

Config files are full replacements:

• Claude Code CLI: ~/.claude/settings.json
• Codex CLI: ~/.codex/config.toml

On first write, an existing config is moved to a sibling backup:

• ~/.claude/settings.json.egw-backup
• ~/.codex/config.toml.egw-backup

Files containing secrets are written with 0600 permissions where the platform supports POSIX modes.

Codex Config Contract

Codex CLI uses the OpenAI Responses-compatible gateway routes. Provider blocks use:

base_url = "https://gateway.example.com/kiro/openai/v1"
experimental_bearer_token = "<virtual-key>"
wire_api = "responses"

The Codex provider uses /codex/openai/v1. The CLI does not use env_key, shell exports, OTel sections, or custom baggage headers.

Development

npm install
npm run typecheck
npm run lint
npm run test
npm run build
npm pack --dry-run