Command-line reference

The optiflume command is installed with OptiFlume. Its commands cover signing in, settings, Claude Code and Codex, updates, diagnostics and removal.

The installer puts optiflume on your PATH for new Terminal windows. If your shell can’t find it, open a new window or use the full path, ~/.optiflume/bin/optiflume. optiflume help (or -h, --help, or no command at all) prints the list below.

Command	What it does
`optiflume status`	Your plan, the routing mode, and whether each part is ready.
`optiflume login [--no-browser]`	Sign this Mac in. Opens your browser; no keys.
`optiflume logout`	Sign this Mac out.
`optiflume refresh`	Fetch your plan now, for example right after subscribing.
`optiflume account`	Who is signed in, and the plan.
`optiflume configure`	Global settings: the mode, cost or quality first, and the Guardian.
`optiflume configure --project`	Settings for the current project only.
`optiflume auto-switch on\|pause\|off\|status`	Switch automatically, suggest only, or no switching.
`optiflume analytics [--days N] [--json] [--savings]`	Routing history and savings, from the log on this Mac.
`optiflume telemetry on\|off\|status`	The daily usage rollup behind your console.
`optiflume stop \| optiflume keep`	Act on a pending model switch from Terminal.
`optiflume notice on\|off\|status \| optiflume notice seconds N`	Turn the Stop/Keep notice on or off, and choose how long it waits.
`optiflume guardian ask\|strict\|allow\|status\|off\|on`	Ask, keep secrets out, or only warn; or turn the Guardian off.
`optiflume allow <file>`	Let agents always read a file the Guardian would stop.
`optiflume update [--check]`	Install the newest version, or only say whether one exists.
`optiflume models`	Download the local models now (normally automatic).
`optiflume harness on\|off\|status`	Claude Code and Codex in VS Code, Cursor and Windsurf.
`optiflume terminal on\|off\|status`	claude and codex in the terminal through OptiFlume.
`optiflume doctor [--bundle]`	Check every part of the install and say what to fix.
`optiflume uninstall [--purge]`	Remove the program and restore editor settings (--purge also deletes local data).
`optiflume version`	The installed version.

optiflume status

Prints the installed version; your plan (and trial days left); the routing mode and preference in force; whether the local models are ready or downloading; and, when Cursor is installed, two lines about Cursor alone: Bridge, whether the OptiFlume Bridge extension is running and for which project folders, and Model list, whether Cursor’s list of models has been built. While Cursor is closed, not running and builds on the next Cursor session are normal. On a Mac without Cursor, a single line says Cursor is not installed. For Claude Code and Codex, run optiflume harness status. The first command to run when something seems off.

optiflume status

optiflume login

Shows a short code and opens optiflume.ai/device. Sign in, check the code matches, and click Authorize this Mac. The command waits until you approve, then fetches your plan. With --no-browser it only prints the address and code, for opening on another device. optiflume activate is the same command.

optiflume login

optiflume logout

Ends this Mac’s session and deletes its license. OptiFlume then does nothing in any tool, the Guardian included: prompts pass straight through, with no routing, until you sign in again. Your settings and history stay. To sign out a Mac you no longer have, use Macs in the console.

optiflume logout

optiflume refresh

A Mac checks its plan by itself about twice a day. Run this to pick up a new subscription, or a cancellation, at once. It prints the plan and the account’s email.

optiflume refresh

optiflume account

Prints, for example, Signed in as you@example.com (Pro trial, 12 days left). Works offline, from the last check-in.

optiflume account

optiflume configure

Asks four questions and saves the answers, keeping every other setting: model switching (on, pause for suggest only, or off), tips about models turned off in Cursor (reserved; no effect in current versions), your preference (cost first or quality first), and the Guardian (ask, strict, allow or off). The first three go in ~/.optiflume/config/routing-config.json, the Guardian in advanced-config.json. Press Return to keep the current answer. See Settings reference.

optiflume configure

optiflume configure --project

Run it from the project folder. It asks for the mode and the preference, each with a “same as global” option, and writes only what you changed to .optiflume/config.json in the project, which every tool reads. Settings from an older .cursor/intent-router.json in the project are carried over. See per-project settings.

cd ~/code/my-project && optiflume configure --project

optiflume auto-switch

on switches automatically, pause suggests only (names the better model, never switches), and off stops switching and suggestions so prompts go straight through; the Guardian and working memory stay on. Only signing out turns everything off. In Claude Code and Codex, suggest only names the better model under your prompt and sends the prompt on yours. status (the default) shows “on”, “paused: suggest only” or “off”, and how recent switches went. See modes.

optiflume auto-switch pause

optiflume analytics

Prints what OptiFlume did (switches, suggestions, prompts you sent your own way), the models that ran, and the estimated spend and saving. --days N limits it to the last N days, --json prints machine-readable output, and --savings prints only the saving. Works offline and on every plan. See Analytics and telemetry.

optiflume analytics --days 7

optiflume telemetry

off stops this Mac sending its daily counts; on resumes; status (the default) says which. Local analytics work either way. The exact fields are listed in Analytics and telemetry.

optiflume telemetry off

optiflume stop | keep

The same as Stop and Keep on the Stop/Keep notice, for a switch in Cursor, Claude Code or Codex. stop cancels the switch and puts your model back; keep puts your model back and sends the prompt on it. In Cursor and in the Claude Code and Codex panels the prompt is not sent. (With codex in a terminal switches are not held, so there is nothing to stop.) With nothing pending they print “No switch is pending.” and exit with status 1. See Stop/Keep.

optiflume stop

optiflume notice

on makes each automatic switch wait for Stop or Keep, in Cursor and in the Claude Code and Codex panels; off switches at once. seconds N sets the wait (switch_notification_seconds): 5 by default, and a value below 3 is raised to 3 (the longest is 60). status shows both. Your other settings in routing-config.json are kept. See Stop/Keep.

optiflume notice seconds 8

optiflume guardian

Sets what the Guardian does when the agent is about to use a secret or a sensitive file, in every tool. ask (the default) pauses and asks you: Claude Code shows its dialog, and in Cursor and Codex the agent asks you in chat (reply allow to let it go ahead once). strict keeps secrets out with no question. allow never stops the agent and warns instead. Deletes and destructive commands ask in every mode. off turns the whole Guardian off and on back on. status (the default) says what happens in the current mode, or “Guardian: off”, and lists the files you always allow. The older stop and warn still work as ask and allow. The choice applies to the next check; there is nothing to restart. See Three modes.

optiflume guardian strict

optiflume allow

Adds the file’s full path to the Guardian’s whitelisted_files, so no tool stops an agent from reading it again, in any mode, including a file such as .env. A relative path is taken from the folder you run it in. To undo it, remove the line from ~/.optiflume/config/advanced-config.json.

optiflume allow config/dev.env

optiflume update

Without options it downloads, verifies and installs the newest version into your user folder, with no password. Cursor and VS Code then ask you to reload the window; Claude Code and Codex use it from the next session. If that cannot run, it falls back to the Terminal installer. --check only compares the installed and available versions. See Updates.

optiflume update --check

optiflume models

The local models (about 1 GB) download in the background after install. Run this to retry a failed download or to fetch them straight away. optiflume status shows progress.

optiflume models

optiflume harness

off stops OptiFlume switching models in the Claude Code and Codex panels and puts your editor settings back exactly as they were. on connects them again; restart or reload the editor to finish, and in Codex approve OptiFlume’s hooks once in Settings → Hooks. status (the default) shows, for each editor, whether Claude Code and Codex are connected, whether the Codex hooks are in place, and whether the terminal commands are on. See Claude Code and Codex.

optiflume harness off

optiflume terminal

on adds OptiFlume’s own claude and codex commands in ~/.optiflume/bin, so claude and codex in a new terminal window switch models through OptiFlume. If you install Claude Code or Codex later, run it again. off removes them, so claude and codex run as before. status (the default) shows the same summary as optiflume harness status.

optiflume terminal on

optiflume doctor

Checks the system, the installed files, your settings, the license, the local models, folder permissions, a test run, recent routing and any open alerts; for Claude Code and Codex, each editor’s connection, the claude and codex terminal commands and the Codex hooks; and, when Cursor is installed, its hook list and the OptiFlume Bridge extension. It prints a fix for each problem. On a Mac without Cursor the Cursor checks are skipped. Warnings about the bridge, Cursor’s auto-switch check and the model list are normal while Cursor is closed. Exit status is 0 when all is well, 1 with warnings, 2 when something is broken. --bundle also saves a support file to your Desktop, with no prompts, code or file paths in it, to send to support@optiflume.ai.

optiflume doctor --bundle

optiflume uninstall

Removes the program and puts your editor settings back as they were: everything added for Claude Code and Codex, the Cursor hooks, the OptiFlume Bridge extension, the rule, the command, the PATH line and the program files. Your settings, history and license stay in ~/.optiflume; add --purge to delete that local data too. Restart Cursor to finish. See Uninstall.

optiflume uninstall

optiflume version

Prints the version number only, for example 1.1.1. Changes in each version are in the changelog.

optiflume version