fluxrouter

Command-line client for the Flux capability platform — web fetch, grounded search, image generation, and one-command MCP server setup.

Why fluxrouter and not flux? The name flux is taken by FluxCD, a CNCF project. Using fluxrouter avoids a collision for anyone who has FluxCD installed.

Install

npx (no install required)

npx @fluxrouter/cli <command>

npm global

npm install -g @fluxrouter/cli
fluxrouter <command>

Homebrew

brew tap fluxrouter/tap
brew install fluxrouter

Quick start

1. Authenticate

Browser PKCE flow (recommended):

fluxrouter login

Opens a browser tab. After you approve, your sk-flux-… key is stored at ~/.config/fluxrouter/credentials.json (mode 0600).

Paste an existing key (CI/scripts):

fluxrouter login --key sk-flux-yourkey

2. Wire flux-tools into your MCP client — the killer feature

fluxrouter mcp install

Auto-detects your installed MCP clients (Claude Code, Codex, Cursor) and writes the flux-tools remote HTTP server entry into each config — your key or a scoped token already wired in. Restart your MCP client and flux-tools appears in the server list with your entitlement.

Options:

# Force a specific client (claude-code | codex | cursor):
fluxrouter mcp install --client claude-code

# Mint a short-lived scoped token instead of embedding your raw key:
fluxrouter mcp install --scoped

# Set the scoped-token lifetime (default 3600s):
fluxrouter mcp install --scoped --ttl 7200

What gets written depends on the client:

| Client | Config file | Format | |---|---|---| | Claude Code | ~/.claude.json | JSON mcpServers | | Codex | ~/.codex/config.toml | TOML [mcp_servers.*] | | Cursor | ~/.cursor/mcp.json | JSON mcpServers |

Existing servers in the config file are always preserved — only flux-tools is added or updated. Re-running mcp install is idempotent.

Capability commands

All commands require fluxrouter login first. Premium capabilities require a paid Flux account; on a free key you get a clear upgrade message (no charge).

fetch — fetch a URL as clean markdown

fluxrouter fetch https://example.com

# Use the premium render tier for JS-heavy / anti-bot pages:
fluxrouter fetch https://spa.example.com --render

The page markdown is written to stdout.

search — grounded web search

fluxrouter search "latest Flux router news"

Sends your query to POST /v1/chat/completions with the hosted web_search tool (model flux-auto). Prints the grounded answer followed by a numbered Sources list (live citations / search_results).

image — generate an image

fluxrouter image "a red cube on a white background"

# Choose an arm (default flux-image-together-flux, the cheapest ~$0.01):
fluxrouter image "a red cube" --model nano-banana-pro-2k

# Write the image to a file instead of printing base64:
fluxrouter image "a red cube" -o cube.png

usage — month-to-date spend

fluxrouter usage

Shows your current key's spend and subscription tier (read from the proxy GET /key/info).

keys — manage your Flux API keys

fluxrouter keys list

Shows your current key's info — alias, masked key, tier, and spend (GET /key/info).

Environment variables

| Variable | Default | Purpose | |---|---|---| | FLUXROUTER_HOME | ~/.config/fluxrouter | Credentials directory (useful in tests / CI) | | FLUXROUTER_API_BASE | https://api.fluxrouter.ai | Override the API base URL | | FLUXROUTER_MCP_URL | https://mcp.fluxrouter.ai/mcp | Override the MCP server URL |

Notes

• No billing logic runs in the CLI — capability fees are computed and billed server-side; the CLI only displays results.
• mcp install --scoped verifies the mint endpoint returns 200 before writing any config. It will never write a dead token.
• usage and keys read the current key's info from the proxy GET /key/info (Bearer-authenticated).
• The login browser flow uses PKCE (RFC 7636 S256) against /desktop/authorize + /desktop/token. For CI, use login --key.

Distribution

• npm: npx @fluxrouter/cli or npm install -g @fluxrouter/cli
• Homebrew: brew tap fluxrouter/tap && brew install fluxrouter (requires the fluxrouter/homebrew-tap repo to exist)
• The Homebrew formula lives at Formula/fluxrouter.rb in this repo; the sha256 is filled in at publish time.

License

MIT