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, and cost or quality first. |
optiflume configure --project | Settings for the current project only. |
optiflume auto-switch on|off|pause|status | Switch automatically, suggest only, or pause. |
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 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 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, or on a Mac without it, not running and builds on the next Cursor session are normal. For Claude Code and Codex, run optiflume harness status. The first command to run when something seems off.
optiflume statusoptiflume 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 loginoptiflume logout
Ends this Mac’s session and deletes its license. Prompts then 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 logoutoptiflume 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 refreshoptiflume account
Prints, for example, Signed in as you@example.com (Pro trial, 12 days left). Works offline, from the last check-in.
optiflume accountoptiflume configure
Asks three questions and saves the answers in ~/.optiflume/config/routing-config.json, keeping every other setting: the routing action (suggest, switch or paused), tips about models turned off in Cursor (reserved; no effect in current versions), and your preference (cost first or quality first). Press Return to keep the current answer. See Settings reference.
optiflume configureoptiflume 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 .cursor/intent-router.json. See per-project settings.
cd ~/code/my-project && optiflume configure --projectoptiflume auto-switch
on switches automatically, off suggests only, and pause turns routing off so prompts go straight through. Suggest only is for Cursor: in Claude Code and Codex, off stops switching altogether for now. status (the default) shows whether automatic switching is on and how recent switches went. See modes.
optiflume auto-switch offoptiflume 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 7optiflume 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 offoptiflume stop | keep
The same as the Stop and Keep buttons on the Stop/Keep notice. stop cancels the switch and puts your model back; keep puts your model back and sends the prompt on it. With nothing pending they print “No switch is pending.” and exit with status 1. See Stop/Keep.
optiflume stopoptiflume 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 --checkoptiflume 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 modelsoptiflume 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 hook once in Settings → Hooks. status (the default) shows, for each editor, whether Claude Code and Codex are connected, whether the Codex hook is in place, and whether the terminal commands are on. See Claude Code and Codex.
optiflume harness offoptiflume 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 onoptiflume 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 hook; and for Cursor, its hook list and the OptiFlume Bridge extension. It prints a fix for each problem. Warnings about the bridge, Cursor’s auto-switch check and the model list are normal while Cursor is closed or not installed. 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 --bundleoptiflume 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 uninstalloptiflume version
Prints the version number only, for example 1.1.1. Changes in each version are in the changelog.
optiflume version