CLI Reference

CLI reference

The cask puts openswap on your PATH. A DMG install has no command until you link it (see Getting started).

openswap list                       list managed accounts
openswap status                     show current account
openswap switch                     rotate to the next account
openswap switch <num|email|alias>   switch to a specific account
openswap add                        add the current account
openswap add-token [TOKEN|-]        register an API key or setup-token
openswap add-token KEY --for <n>    link an API key to account n as its API credit
openswap remove <num|email>         remove an account
openswap disable <num|email>        hold an account out of auto-rotation
openswap enable <num|email>         return a disabled account to rotation
openswap alias <num|email> <name>   set a short alias
openswap alias <num|email> --unset  remove an alias
openswap alias                      list aliases
openswap swap <a> <b>               exchange two slots
openswap move <a> <slot>            assign an account to a slot
openswap auto                       auto-switch near rate limits
openswap config [set KEY VALUE]     show or change shared policy
openswap unclaimed [--purge ID]     list or drop stashed credentials
openswap export <path>              export accounts
openswap import <path>              import accounts
openswap menubar                    macOS extra (foreground)
openswap setup                      save the current login and start the extra at login
openswap menubar --install-service  keep the extra running at login
openswap widget --install           macOS Desktop / Notification Center widget
openswap statusline --install       wrap Claude Code status line (opt-in)
openswap statusline --codex         paint the live Codex account label (no config.toml wrap)
openswap upgrade                    the cask: prints brew upgrade --cask openswap; a source install: pull and reinstall
openswap uninstall [--zap]          remove OpenSwap from this Mac (--zap: and its saved accounts, settings and logs)
openswap purge                      remove all OpenSwap data
openswap --version
openswap help

Codex CLI

openswap codex add|list|switch|remove|disable|enable|alias
openswap codex export|import|swap|move
openswap codex desktop status <n>
openswap codex desktop switch <n> --confirm-restart --confirm-idle
openswap codex desktop recovery-status
openswap codex desktop recover --confirm-restart --confirm-idle

codex desktop is experimental ChatGPT quit/switch/relaunch. ChatGPT.

Remote tasks

openswap worker connect [url]       pair this Mac by approving it in your browser (or reconnect an expired key)
openswap worker pair <url> <code>   pair with the command OpenTag shows
openswap worker setup               guided setup: the worker, the account and the folders
openswap worker status              the worker, the service link and the running task
openswap worker enable|disable      start or stop the worker
openswap worker account [slot]      list the accounts, or pin the one tasks run on
openswap worker workspace           the folders tasks work in or read
openswap worker worktrees           list the tasks' worktrees, or prune finished ones
openswap worker live-check          run a few short real tasks and record the evidence
openswap worker live status         whether live tasks are on
openswap worker permissions         this Mac's limit on what tasks may do
openswap worker origins             where tasks may come from
openswap worker stop|pause          stop the running task, or stop taking new ones
openswap worker unpair              forget the pairing

openswap worker --help lists every one. Guide: Remote tasks.

Aliases: ls = list, rm = remove.

Original flag spellings (openswap --switch, openswap --list, …) still work.

Useful flags

openswap switch --strategy best
openswap switch --strategy next-available
openswap list --token-status
openswap list --json
openswap add --slot 3
openswap add --alias work
openswap add-token sk-ant-oat01-... --email you@example.com
openswap add-token sk-ant-api03-... --for 1
openswap auto --once --json
openswap auto --strategy consume-first
openswap auto --model Fable
openswap config set autoswitch.threshold 80
openswap config set autoswitch.codexEnabled false
openswap menubar --service-status
openswap widget --status
openswap widget --uninstall
openswap statusline --uninstall
openswap uninstall --zap

JSON

list, status, and switch take --json (one object on stdout; notices on stderr). openswap auto --json is an event stream.

{
  "schemaVersion": 1,
  "activeAccountNumber": 2,
  "accounts": [
    {
      "number": 2,
      "email": "you@example.com",
      "active": true,
      "usageStatus": "ok",
      "usage": {
        "fiveHour": { "pct": 25.0, "resetsAt": "2026-06-22T23:29:59Z" },
        "sevenDay": { "pct": 16.0, "resetsAt": "2026-06-26T17:59:59Z" }
      }
    }
  ]
}

Handled errors: {"schemaVersion":1,"error":{...}} and a non-zero exit. New fields may appear; ignore ones you do not know.

Weekly windows may include pace fields (expectedPct, aheadOfPace, projectedExhaustionAt) once the week is about a day old. Disabled rows carry "disabled": true. Aliases appear as "alias": "work" when set.

After a switch, do I restart?

Usually no. macOS Keychain is cached ~30 seconds. Restart Claude Code only if you want the new account instantly.

You can keep the same conversation after switching. The first message on the new account may use extra usage while the conversation cache rebuilds.

ChatGPT desktop switching always quits and relaunches the app. ChatGPT.

Gone

openswap tui, watch, run, map, and unmap exit 2. Use the extra or openswap list / openswap switch. Sessions.