omnimux CLI

User-level command-line interface for OmniMux, a unified AI gateway built on the open-source new-api project by QuantumNous.

Query models, pricing, groups, and balance, and manage your own API tokens — with an Agent RPC JSON envelope (contract_version: 1 since 0.3.0) and a hard guarantee that sk- keys never touch stdout/stderr.

Breaking wire notes: CHANGELOG.md · docs/ERROR_CONTRACT.md.

Package name: published as @omnimux/cli on npm.
Binary releases: https://github.com/laozhong86/omnimux-cli/releases
Source of truth: this directory in the OmniMux monorepo (cli/). The public omnimux-cli repo is a release surface only.

Install

One-liner (macOS / Linux)

curl -fsSL https://omnimux.ai/install.sh | bash
omnimux help

The installer downloads a prebuilt binary from laozhong86/omnimux-cli into /usr/local/bin or ~/.local/bin.

Version pin:

curl -fsSL https://omnimux.ai/install.sh | bash -s -- --version 0.2.0

npm / pnpm / bun (Node >= 18 or Bun)

npm install -g @omnimux/cli    # or: pnpm add -g @omnimux/cli  /  bun add -g @omnimux/cli
omnimux login                  # browser device-code sign-in
omnimux help

Hackable (inspect published package source)

npm pack @omnimux/cli
tar -xzf omnimux-cli-*.tgz && cd package
npm link
omnimux help

Windows

powershell -c "irm https://omnimux.ai/install.ps1 | iex"
omnimux help

Or npm: npm install -g @omnimux/cli. Or download omnimux-windows-x64.exe from GitHub Releases.

Default instance

The CLI connects to the official instance https://omnimux.ai out of the box — no configuration needed for public commands like omnimux pricing. Self-hosted users (or anyone targeting another instance) override it with --base-url, the OMNIMUX_BASE_URL env var, or omnimux config set base_url <url>.

Quick start

# 1. (Optional) Point the CLI at your own instance — it defaults to the
#    official instance https://omnimux.ai
omnimux config set base_url https://your-instance.example.com

# 2. Sign in via browser (device code). Stores system access token + user_id
#    securely (Keychain / 0600 secrets file). Replaces any existing system PAT.
omnimux login

# Manual alternative (if you already have a PAT from the web console):
#   omnimux config set access_token <your-access-token>
#   omnimux config set user_id <your-user-id>

# 3. First commands
omnimux pricing --pretty      # public, no token needed
omnimux models --pretty
omnimux balance --pretty

Everything is also overridable per-invocation: omnimux --base-url https://... models, or via env vars OMNIMUX_BASE_URL / OMNIMUX_ACCESS_TOKEN / OMNIMUX_USER_ID. Priority: flag > env > config file > built-in default (https://omnimux.ai).

Commands

| Command | Description | |---------|-------------| | omnimux models | Models available to you | | omnimux pricing | Public model price list (no token needed) | | omnimux groups | Your groups and ratios | | omnimux balance | Balance and usage (adds derived.*_usd fields) | | omnimux tokens | List API tokens (keys always masked) | | omnimux tokens create <name> [--group=g] [--quota=usd] | Create a token; the key is never displayed. Output includes token_id — from the server response when available, otherwise resolved via a follow-up masked list call | | omnimux tokens switch-group <id> <group> | Move a token to another group | | omnimux tokens copy <id> | Copy the real key straight to the clipboard | | omnimux tokens apply <id> <file> | Replace __OMNIMUX_TOKEN_<id>__ in a file with the real key, atomically | | omnimux tokens exec <id> [--timeout=sec] -- <cmd...> | Run a command with __OMNIMUX_TOKEN_<id>__ substituted; output sanitized. Child timeout: 300s default, override with --timeout=<sec> | | omnimux login [--no-open] | Browser device-code login; stores system access token | | omnimux logout | Clear stored access token and user_id | | omnimux scan-config <file> | Show a config file with secrets redacted (best-effort) | | omnimux config [get\|set\|unset] | View/set base_url, user_id, access_token, auto_update | | omnimux update [--check] [--force] | Self-update (npm global or release binary). Also migrates legacy geminix.cc base_url → official default | | omnimux upgrade | Alias for update | | omnimux help | Usage overview |

Global flags: --base-url <url>, --pretty, --version, --check / --force (for update), --no-auto-update.

Auto-update (default on)

On normal command runs the CLI may self-update in the background (at most once per 24h):

• Default: enabled
• Disable permanently: omnimux config set auto_update false
• Disable via env: export OMNIMUX_AUTO_UPDATE=0
• Disable once: omnimux --no-auto-update <command>
• Re-enable: omnimux config set auto_update true or omnimux config unset auto_update
• Notices go to stderr only (stdout stays JSON). The current process finishes on the old version; the next run uses the new one.
• Skipped for update/upgrade, source checkouts, and when offline/throttled.

Security

• Keys never print. Token list/show responses mask key fields; the real key flows only from the API into the clipboard (child-process pipe), a placeholder in your config file (atomic write), or a child command (output re-sanitized). No command can be made to echo a full sk- key.
• Secrets are stored properly. access_token goes to the macOS Keychain (service omnimux) or ~/.config/omnimux/secrets.json (mode 0600); never to config.json.
• Output contract (Agent RPC). Success: stdout { ok, data, meta }; errors: stderr { ok:false, error, meta } (typed type/subtype/recovery). Exit: 0 ok, 1 api, 2 config/auth, 3 usage, 4 network, 5 internal, 10 confirmation. See docs/ERROR_CONTRACT.md. Discover commands with omnimux schema.
• User-level only. The CLI ships no admin endpoints; test/no-admin.test.js scans the source and fails the build if any admin route prefix appears. For instance operations/administration, use the separate newapi agent skill.

AI editor skill

Package ships a flat skill tree under skill/ (one directory per Agent skill). Install:

omnimux skill install --user       # ~/.agents/skills/omnimux + recreate-viral-video + …
omnimux skill install --project    # <repo>/.agents/skills/<id>
omnimux skill status
omnimux skill update --project     # also migrates legacy whole-tree installs from 0.2.6

| Mode | Behavior | | --- | --- | | link (default) | Each .agents/skills/<id> → package skill/<id> | | copy | Snapshot + .omnimux-skill-meta.json; run skill update after CLI upgrades |

| skill id | Role | | --- | --- | | omnimux | Shared: CLI, auth, tokens, secrets | | recreate-viral-video | Business: viral/reference video safe adaptation |

There is no nested packs/ layer — Agents discover skills as siblings.

Development

cd cli
bun test                    # unit + guard tests (contract tests skip without a live instance)
bun src/bin.js help         # run from source
bun run build:binaries      # dist/ single-file binaries for 4 platforms (requires bun)

Releasing (maintainers / Agents)

See cli/AGENTS.md and .agents/skills/cli-release/SKILL.md.

• Bump package.json version → tag cli-vX.Y.Z on monorepo → CI builds binaries and publishes to laozhong86/omnimux-cli (+ optional npm).
• Do not tag CLI releases as bare vX.Y.Z (gateway workflows).

Live-instance contract tests:

OMNIMUX_TEST_BASE_URL=http://localhost:7001 \
OMNIMUX_ACCESS_TOKEN=... OMNIMUX_USER_ID=... \
bun test test/contract.test.js

License & attribution

This project is a fork of new-api, Copyright © QuantumNous and contributors, licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE and NOTICE at the repository root. All upstream attribution is preserved as required.