cgw — FloTorch Coding Gateway CLI

Wire your AI coding tools through a corporate gateway in one command. One API key, per-seat attribution, budget + rate limits, secret-scanning, usage reporting — without every developer manually editing config files.

npm i -g @flotorch/gateway-cli   # or: pnpm add -g @flotorch/gateway-cli
cgw auth login
cgw configure

That's the whole onboarding. Pick a tool, pick a scope, done.

Requirements

• Node.js >= 20

What it does

• Signs you in with a per-seat API key issued by your gateway admin.
• Writes the right config file for each supported coding tool so its model traffic routes through the gateway instead of calling upstream providers directly.
• Picks the right scope (global, project-wide, or per-machine) based on what you want and what the tool supports.
• Installs an acceptance-tracking hook that fires at session end for tools that expose lifecycle events. Feeds the gateway's usage reporting.
• Stays out of your way. Idempotent writes. Deep-merges into existing settings files — won't clobber your theme, your other hooks, your existing env vars.

Supported tools

| Tool | Config path (user scope) | Scopes | Key storage | Hooks wired | | -------------------------------- | ---------------------------------------- | ---------------------- | ---------------------------------------------------------- | -------------------------------------- | | Claude Code | ~/.claude/settings.json | user / project / local | literal in JSON (ANTHROPIC_AUTH_TOKEN) | Stop + SessionEnd | | opencode (sst/opencode) | ~/.config/opencode/opencode.json | user / project / local | literal (user + local); env-var reference in project scope | — | | qwen-code (Alibaba Qwen CLI) | ~/.qwen/settings.json + ~/.qwen/.env | user / project / local | .env file alongside settings (envKey reference) | Stop + SessionEnd | | codex (OpenAI codex CLI) | ~/.codex/config.toml | user only | shell env var (codex does not auto-load .env) | not wired |

Each writer emits both Anthropic and OpenAI-compatible provider entries where the tool supports both wire formats. codex is OpenAI-only.

Scope model

Three scopes, same names across every supported tool that allows more than one:

| Scope | Where the file lives | Committed to git? | Recommended for | | --------- | ------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------------- | | user | your home directory (~/.claude/…, ~/.codex/…, etc.) | no (outside the repo) | your personal default across every project | | project | this repo's config dir (./.claude/settings.json, etc.) | yes — shared with teammates | base URL only; we never embed the API key here | | local | this repo's local-override file (./.claude/settings.local.json, ./opencode.json, ./.qwen/) | no — auto-gitignored | the usual default: per-seat API key stays on your machine |

local is the default when you don't pass --scope. The CLI adds gitignore entries automatically for tools that don't natively ignore their local file.

Secret hygiene: project scope will never write your API key to disk. It writes an env-var reference ({env:FLOTORCH_GATEWAY_KEY} or an envKey field) and prints a note telling you to export the variable yourself. This is the only safe way to commit a config file.

Commands

cgw auth login                         # sign in — prompts for gateway URL + API key
cgw auth logout                        # delete local credentials; hooks are left in place
cgw auth whoami                        # print identity the current API key resolves to
cgw configure                          # interactive: pick tools, pick scope
cgw configure claude-code --scope local # non-interactive: scriptable for onboarding
cgw configure --all                    # every supported tool at once
cgw configure opencode --scope user    # wire up opencode globally
cgw models list                        # list models you can reach through the gateway
cgw models list --kind chat            # filter by kind: chat or embedding
cgw models list --json                 # emit raw JSON for scripting
cgw models sync                        # refresh model list in an existing opencode.json
cgw models sync --scope local          # with explicit scope
cgw models sync --path /path/to/opencode.json  # with explicit path
cgw usage                              # show your gateway usage (today by default)
cgw usage --days 7                     # last 7 days
cgw usage --json                       # emit raw JSON for scripting
cgw status                             # who am I, where am I pointed, what models can I use
cgw doctor                             # health checks: creds, network, hook install, settings
cgw version                            # print CLI version
cgw init                               # writes .coding-gateway.json (projectName + ticket pattern)
cgw init --project my-app              # with explicit project name
cgw init --ticket-pattern "JIRA-\d+"   # with custom ticket extraction regex

Every command supports --help. Commands that need input will prompt interactively when flags are missing, but every flag still works for scripting.

Auth options

cgw auth login --gateway-url https://gateway.corp.com       # non-interactive URL
cgw auth login --api-key "$GATEWAY_KEY"                      # non-interactive key
cgw auth login --gateway-url https://gateway.corp.com --api-key "$KEY"  # fully scriptable

Typical flows

First-time onboarding (what to put in your team wiki):

cgw auth login              # paste the gateway URL + API key your admin emailed you
cgw configure claude-code   # default scope is local — safe per-seat, gitignored
cgw doctor                  # confirm everything's wired

Configuring multiple tools in one go:

cgw configure --all --scope local

CI-friendly, no prompts:

cgw auth login --gateway-url https://gateway.corp.com --api-key "$GATEWAY_KEY"
cgw configure claude-code --scope user

Inspecting what got written:

cgw status
cgw doctor

Checking your usage:

cgw usage --days 30
cgw usage --json | jq .totals

Syncing models for opencode:

cgw models sync --scope local   # refresh model list after admin adds models

Safe config merging

cgw configure adds the gateway settings to your existing config files without overwriting what's already there:

• Your theme, custom env vars, and other hooks are left untouched.
• Running cgw configure a second time won't create duplicate entries — it's safe to re-run.
• If a config file is corrupted or in an unexpected format, we'll let you know instead of overwriting it.

Credentials

Stored at ~/.config/cgw/credentials.json (chmod 0600). Contains gateway URL, API key, user ID, email, and a timestamp. cgw auth logout deletes this file.

cgw doctor warns if the file mode is looser than 0600.

Override the config root with CGW_CONFIG_DIR.

Limitations

• Cursor requires manual setup. Cursor stores its settings in an internal database, so the CLI can't configure it automatically. Find step-by-step instructions on your gateway dashboard.
• codex is user-scope only. codex (OpenAI's CLI) has no project or local config. cgw configure codex --scope project returns a skipped status with a clear message.
• codex doesn't auto-load .env. After configuring codex, export FLOTORCH_GATEWAY_KEY in your shell rc yourself. The CLI prints the line to paste.

Config file reference

| Tool | File | Format | | ----------------- | --------------------------------------------------------- | ---------------------- | | Claude Code | ~/.claude/settings.json / .claude/settings.local.json | JSON | | opencode | ~/.config/opencode/opencode.json / ./opencode.json | JSON (JSONC tolerated) | | qwen-code | ~/.qwen/settings.json / .qwen/settings.json | JSON | | qwen-code secrets | ~/.qwen/.env / .qwen/.env | dotenv | | codex | ~/.codex/config.toml | TOML | | cgw credentials | ~/.config/cgw/credentials.json | JSON (chmod 0600) | | cgw hook script | ~/.config/cgw/hooks/acceptance.sh | shell |