ScaleMax CLI

Universal installer for configuring AI coding clients to use the ScaleMax OpenAI- and Anthropic-compatible API gateway.

ScaleMax CLI is designed to be run from any machine with Node.js installed:

npx scalemax

It detects supported AI coding clients, safely backs up existing config files, and writes ScaleMax-compatible configuration using your ScaleMax API key.

Requirements

• Node.js 18.19 or newer
• macOS, Linux, or Windows
• A ScaleMax API key
• Network access to https://api.scalemax.pro

The CLI identifies whether the supplied key belongs to the API-credit surface or the token-pack surface. It then stores and configures the matching base URL automatically; users do not need to choose it manually.

Installation

One-time run with npx

npx scalemax

Always use the latest published version

npx scalemax@latest

Global install

npm install -g scalemax
scalemax

Quick Start

npx scalemax

If no ScaleMax configuration exists, the installer prompts:

Enter your ScaleMax API key:

If configuration already exists, the installer preserves the existing flow:

✓ Existing ScaleMax configuration detected.

API key:
••••••••••••••••abcd

1. Keep existing key
2. Replace with new key
3. Remove configuration
4. Exit

After authentication, ScaleMax CLI detects installed clients and lets you configure one client or all detected clients.

Commands

scalemax              Interactive installer
scalemax login        Store or replace your ScaleMax API key
scalemax logout       Remove stored ScaleMax API key
scalemax doctor       Run diagnostics
scalemax models       List available ScaleMax models
scalemax helper-bot   Open the ScaleMax-only support assistant
scalemax claude-tools Install bounded GitHub skill tools for Claude
scalemax update       Reconfigure detected clients with the stored key
scalemax remove       Remove ScaleMax-generated client configuration
scalemax --help       Show help
scalemax --version    Show installed version

Authentication

ScaleMax CLI stores your API key in a user-level configuration file:

• macOS: ~/Library/Application Support/scalemax/config.json
• Linux: $XDG_CONFIG_HOME/scalemax/config.json or ~/.config/scalemax/config.json
• Windows: %APPDATA%\scalemax\config.json

The file is written with private permissions where supported. The API key is never printed; existing keys are displayed only as a masked value such as ••••••••••••••••abcd.

For CI or non-interactive checks, you may provide the key through the environment:

SCALEMAX_API_KEY=sm_live_xxx scalemax models

ScaleMax Helper Bot

Start an interactive ScaleMax installation, configuration, authentication, and troubleshooting session:

npx scalemax@latest helper-bot

Or ask one small question and exit:

npx scalemax@latest helper-bot "Why is my ScaleMax API key rejected in Codex?"

The helper uses the same stored key as the installer, verifies authentication, and detects the API-credit or token-pack base URL automatically. General support questions default to gpt-5.4 when that model is available to the key; each response is capped at 512 tokens and interactive history is bounded to the latest two turns. To choose a different model from scalemax models, use:

npx scalemax@latest helper-bot --model fable-5 "Help me configure ScaleMax in Cursor"

Recognized setup, repair, and verification requests execute the CLI's allowlisted client operations directly. Requests such as setup all providers, fix Hermes request failed, configure Claude Code, verify OpenCode, and setup vs code roo extension for claude are handled by the controller before any model request. The controller detects the relevant client, runs a safe installer when the client has one, verifies existing ScaleMax configuration, repairs ScaleMax-managed files when verification fails, re-verifies, and reports each step.

For Claude tool access, run scalemax claude-tools, or ask helper-bot to install GitHub skill tools for Claude Desktop and Claude Code. Claude Code receives Anthropic's official example-skills@anthropic-agent-skills plugin plus public-GitHub read permissions. Claude Desktop/Cowork receives a local MCP server with only three tools: github_fetch, github_tree, and github_install_skill. The MCP server accepts only public GitHub HTTPS hosts, limits downloads, rejects unsafe archive paths and symlinks, refuses to replace an existing skill, and can write only beneath ~/Claude/skills. It does not expose a general shell, arbitrary URLs, or unrestricted filesystem access. Restart Claude Desktop after installation and use Cowork or Code; a normal Chat tab does not expose local tools. Only install skills from repositories you trust: a SKILL.md is instruction content that Claude may follow after installation, even though the bridge itself cannot execute arbitrary repository code.

For Roo Code, helper-bot can install VS Code on Windows with the fixed Microsoft winget package, install the official Roo Code extension, write OpenAI and Claude ScaleMax profiles when the key exposes those families, and verify the import handoff. For DeepSeek V4 Flash, helper-bot creates an agent profile only when authenticated discovery reports capabilities.tools=true; otherwise it installs Continue's safe Chat/Edit fallback. For general troubleshooting that cannot be completed by a fixed client action, helper-bot sends a small gpt-5.4 request grounded with bundled ScaleMax documentation about stored authentication, credit/token base URLs, provider scope, client setup, and common errors. The language model never generates or executes shell commands; only fixed ScaleMax client detection, installation, configuration, verification, and rollback operations are available to the controller.

The helper refuses unrelated requests and redacts ScaleMax-style secrets from prompts, provider output, errors, and progress notifications. Use /status for non-secret connection details, /help for commands, and /quit to exit.

Supported clients

scalemax supports this client set whether it is run through a global install or with npx:

• Codex
• Cursor
• Roo Code (VS Code)
• Cline (CLI and VS Code)
• Continue (VS Code)
• TRAE SOLO
• Claude Code
• OpenCode
• OpenClaw
• Hermes
• Cherry Studio
• API Code

For clients without a stable official config file, the installer writes a ScaleMax setup guide under ~/.scalemax/ instead of modifying private app storage.

Codex

ScaleMax configures the official Codex custom-provider interface in ~/.codex/config.toml with wire_api = "responses", and stores the selected key in Codex's private ~/.codex/auth.json. Detection is semantic: unrelated or ChatGPT-authenticated Codex files are not reported as ScaleMax-configured. Only authenticated Codex/OpenAI-family models are eligible, the generated files are private, and verification performs a minimal /v1/responses request before reporting success.

Claude Code

ScaleMax updates ~/.claude/settings.json with ANTHROPIC_BASE_URL=https://api.scalemax.pro, gateway model discovery, and a cached apiKeyHelper that reads a private ~/.claude/scalemax.key file. The raw key is not stored in the settings JSON. Because Claude Code's gateway discovery only accepts IDs beginning with claude or anthropic, catalogs that include Fable or Auto also receive a managed custom picker entry (ANTHROPIC_CUSTOM_MODEL_OPTION=fable-5 or auto, with friendly names and descriptions), making /model fable-5 and /model auto selectable; any prior custom picker values are restored when ScaleMax configuration is removed. The Anthropic base URL intentionally has no /v1 suffix because Claude Code adds /v1/messages itself. The CLI preserves unrelated settings, selects a live main model from the authenticated catalog (preferring claude-opus-5), pins authenticated Haiku for lightweight background work when available, and sets CLAUDE_CODE_DISABLE_THINKING=1 because third-party Anthropic-compatible providers do not support Claude Code's proprietary extended-thinking control envelope. The ScaleMax gateway separately locks native Claude requests to provider-side low effort. Fable uses its verified translated controls and supports low, medium, high, and max, with low as the default. Haiku 4.5 omits the unsupported effort field. It verifies a one-token Messages request and, if verification fails, removes only the ScaleMax-managed changes. Claude Code picker aliases such as claude-opus-5[1m] are normalized by the gateway.

OpenCode

ScaleMax merges a named scalemax provider into ~/.config/opencode/opencode.json (or the platform-equivalent config directory). It uses https://api.scalemax.pro/v1, reads its credential from the private ~/.config/opencode/scalemax.key file through OpenCode's {file:...} substitution, keeps unrelated providers and the user's non-ScaleMax default model, and exposes only authenticated Codex/OpenAI-family models. A fresh ScaleMax setup uses an authenticated GPT mini model as small_model when available. Each generated model has an explicit output limit of at most 4096 tokens so OpenCode does not send an unsupported default limit. Its tool_call flag is taken from the authenticated ScaleMax model catalog; run scalemax update after a catalog or client update so agent tools stay aligned with the current route.

OpenClaw

ScaleMax partitions OpenClaw models into native openai-responses (scalemax-codex, /v1), OpenAI-compatible openai-completions (scalemax-deepseek, /v1), and anthropic-messages (scalemax-claude, origin) providers. deepseek-v4-flash is always isolated in the Chat Completions provider and never advertised through Responses. Its agent flags come only from authenticated catalog discovery: tools, forced tool_choice, reasoning, reasoning effort, streamed usage, and reasoning_content replay are each enabled only when the exact model advertises that capability. In particular, a tool-capable route is never forced to replay reasoning content unless capabilities.reasoning_replay=true; a fallback route remains explicitly tool-free. The API key and compatibility User-Agent are OpenClaw file-backed SecretRefs stored in private 0600 files under ~/.openclaw/secrets/; neither value is embedded in the main provider JSON. Migration removes the obsolete mixed provider, preserves the active model family, and scrubs plaintext credentials from generated ScaleMax agent registries even when they contain an older key. Output is capped at 4096 tokens, private-network routing is denied for the public gateway, and unrelated providers and agent settings are preserved.

Hermes

ScaleMax creates family-specific Hermes providers in ~/.hermes/config.yaml and stores one credential in ~/.hermes/.env with private permissions. scalemax-codex uses Hermes's codex_responses transport at /v1; scalemax-claude uses anthropic_messages at the gateway origin; and an authenticated tool-capable deepseek-v4-flash route receives a separate scalemax-deepseek Chat Completions provider. A text-only DeepSeek route fails closed for Hermes agent mode. All providers use a scoped ScaleMax-Hermes/1.0 user agent and a 4096-token output cap. Existing non-ScaleMax providers and defaults are preserved, and the obsolete mixed provider is migrated safely.

Roo Code (VS Code)

Roo Code stores provider profiles and secrets in VS Code extension storage, so ScaleMax does not mutate its private database. Instead, the CLI writes a private 0600 Roo settings-import file at ~/.scalemax/roo-code-import.json and points the supported roo-cline.autoImportSettingsPath VS Code setting at it. Codex, Claude, and tool-capable DeepSeek profiles remain separate. DeepSeek is offered only when authenticated discovery reports capabilities.tools=true; otherwise Roo fails closed and points the user to Continue Chat/Edit. Reload VS Code once so Roo imports supported profiles into its SecretStorage. CLI verification intentionally reports the handoff as verified, not the extension runtime, until that reload occurs.

Cline (CLI and VS Code)

ScaleMax supports the verified Cline CLI 3.0.47 and VS Code extension 4.0.12 formats. The CLI surface uses Cline's built-in openai-native provider and Responses protocol. The extension uses its built-in OpenAI-compatible provider. Both receive the raw ScaleMax key and the matching credit or token base URL; ScaleMax never writes a custom Authorization or x-api-key header because Cline generates Authorization: Bearer … itself. Configuration is attempted only while Cline and VS Code are stopped, preserves unrelated state, uses private atomic files with backups and rollback, and fails closed on unknown versions or malformed/symlinked state.

Continue (VS Code)

Continue is the universal VS Code Chat/Edit route for deepseek-v4-flash. The CLI installs the official Continue.continue extension when VS Code is available, merges an OpenAI-compatible model into ~/.continue/config.yaml, sets useResponsesApi: false, and keeps the authenticated ScaleMax key in private ~/.continue/.env rather than the YAML. Existing Continue models and environment entries are preserved. Reload VS Code and select ScaleMax DeepSeek V4 Flash. For agent workflows, prefer Roo/OpenClaw/Hermes when the authenticated catalog reports capabilities.tools=true.

Cursor BYOK routing on macOS

Cursor can send named models through its own plan-gated router unless its local BYOK runtime is active. When you select Cursor, npx scalemax:

1. Fetches the complete authenticated model list from https://api.scalemax.pro/v1/models.
2. Asks before closing Cursor and modifying the application.
3. Verifies one known semantic patch anchor in each of three Cursor bundles before writing anything.
4. Stores backups outside Cursor.app, records SHA-256 hashes, and rolls back all files if any step fails.
5. Enables Cursor's local BYOK runtime without hard-coding GPT-5.5.
6. Stores the ScaleMax key in Cursor's native macOS protected-secret format and sets useOpenAIKey=true with openAIBaseUrl=https://api.scalemax.pro/v1.
7. Synchronizes every live ScaleMax model into Cursor's local-provider catalog while preserving the user's currently selected model.

Automatic Cursor patching is currently verified on macOS only. Unknown, partial, or changed Cursor bundle signatures fail closed without modifying the app. Cursor updates can replace the patched bundles; rerun npx scalemax@latest after an update. scalemax remove restores only bundle versions and protected-state values managed by ScaleMax, and refuses to overwrite files changed afterward.

For explicitly approved non-interactive automation, set SCALEMAX_CURSOR_PATCH_CONSENT=1. Without it, non-interactive Cursor modification is skipped safely.

Examples

List models:

npx scalemax models

The model list is fetched live from https://api.scalemax.pro/v1/models every time, so disabled or unsupported models disappear immediately without manual cache cleanup. The CLI authenticates the key before loading its model catalog. Safe GET checks receive one short, jittered retry on transient network, rate-limit, or server failures; model-generation POST requests are never retried by the installer. CLI requests honor HTTP_PROXY, HTTPS_PROXY, and NO_PROXY and automatically try the usable IPv4 or IPv6 route.

Run diagnostics:

npx scalemax doctor

Configure all detected clients after login:

npx scalemax update

Remove ScaleMax-generated client config and restore backups when available:

npx scalemax remove

Updating

With npx:

npx scalemax@latest

With a global install:

npm update -g scalemax
# or
npm install -g scalemax@latest

Removing configuration

Remove only the stored ScaleMax API key:

scalemax logout

Remove ScaleMax-generated client configuration files and restore backups when possible:

scalemax remove

Troubleshooting

No ScaleMax API key found

Run:

scalemax login

API check failed: HTTP 401

Your key is missing, expired, inactive, or mistyped. Run:

scalemax login

Then paste a valid ScaleMax API key.

npx runs an old version

Force latest:

npx scalemax@latest

Or clear the npm cache:

npm cache verify

Could not reach the ScaleMax API

Use the latest CLI first:

npx scalemax@latest

ScaleMax automatically honors HTTP_PROXY, HTTPS_PROXY, and NO_PROXY when a workplace or ISP requires an outbound proxy. It also falls back between IPv4 and IPv6. If the error specifically reports DNS or TLS, correct the device DNS/system clock or disable HTTPS inspection for api.scalemax.pro, then rerun the command. Never disable TLS verification.

Client config looks wrong

Run:

scalemax doctor

Then reconfigure:

scalemax update

Remove and start over

scalemax remove
scalemax logout
npx scalemax@latest

Release process for maintainers

See RELEASE.md in the repository. In short:

npm run version:patch   # or version:minor / version:major
npm run prepublishOnly
npm publish

Never publish over an existing npm version. Use semantic versioning for every release.

Safety guarantees

• Existing client configuration files are backed up before writes.
• Writes are atomic.
• Identical configurations are not rewritten or backed up again.
• Invalid JSON/JSON5 client files fail closed instead of being replaced; valid JSON5 values are merged safely.
• Backup directories are user-only and backup files are written with private permissions.
• API keys are masked in terminal output.
• Codex, Claude Code, OpenCode, OpenClaw, Hermes, and the Roo Code import handoff keep generated client credentials in private files rather than shared provider configuration blocks.
• The published npm package contains only runtime files: dist/, README.md, LICENSE, and package.json.
• Tests, TypeScript source, scripts, local caches, .env files, tarballs, and node_modules are excluded from the published package.

FAQ

Does npx scalemax install anything permanently?

npx downloads and runs the CLI package. The CLI itself writes ScaleMax configuration only after you choose to configure clients.

Can I use it without global install?

Yes. Use:

npx scalemax@latest

Can I use a different API key later?

Yes. Run:

scalemax login

or rerun the installer and choose Replace with a new key.

Does it support Windows?

Yes. The CLI uses Windows-aware config paths and writes %APPDATA%\scalemax\config.json for ScaleMax key storage.

What endpoint does it configure?

API-credit keys use https://api.scalemax.pro/v1 for OpenAI-compatible clients and https://api.scalemax.pro for Anthropic-compatible clients. Token-pack keys use https://api.scalemax.pro/token/v1 and https://api.scalemax.pro/token respectively. The CLI detects the key type and configures the correct surface automatically; the two key types are intentionally not interchangeable.