CLI reference

Every subcommand and flag of fred. For the in-REPL slash commands (/cost, /think, /save, …), see slash commands.

Subcommands

CommandWhat it does
fredOpen the interactive REPL.
fred -p "<prompt>"One-shot mode — runs once, prints, and exits.
fred loginBrowser PKCE auth. Writes ~/.config/fred/credentials.json (mode 0600).
fred login --device-codeRFC 8628 device flow for headless boxes (SSH, no browser).
fred logoutRevoke the active key server-side and delete the local credentials file.
fred whoamiPrint account email, balance, and key prefix.
fred updatePoll PyPI for a newer fredcode release. Installs and re-execs into the new binary if found.
fred update --checkJust report whether a newer version is available. No install.
fred update --yesSkip the confirmation prompt before installing the upgrade.
fred update --no-runInstall the upgrade but don't re-exec the new binary.

Flags

FlagEffect
-p, --prompt <text>One-shot mode. Streams a single answer to stdout and exits.
--yoloSkip the permission prompt for every tool call. Deny rules still apply.
--planStart in plan mode (read-only, propose-only). Toggle with /mode or Shift+Tab.
--no-streamDisable rich.Live streaming. Use this in tmux, some Windows terminals, or when piping output.
--model <name>Override the main slot at startup. One of deepseek-v4-flash or deepseek-v4-pro.
--architectAccepted for forward-compat with future planning subagents. Currently a no-op.
--output-style concise|explanatorySet the response verbosity. Default: concise.
--sandbox ro|workspace-write|fullSet the sandbox mode at startup.
--approval untrusted|on_request|neverSet the approval mode at startup.
--no-confirm-proSkip the once-per-account /pro confirmation prompt.
--versionPrint the fredcode version and exit.

Most flags are also reachable mid-session via slash commands — /sandbox, /mode, /style, /yolo. CLI flags set the starting state; slash commands change it on the fly.

Exit codes

0 success. Non-zero on error — the exact code maps to the failure type:

  • 1 — generic user-facing error (bad flag, model unavailable, prompt missing).
  • 2 — insufficient credits. Top up at /billing.
  • 3 — auth required. Run fred login.
  • 4 — sandbox/permission denial that the user explicitly rejected.
  • 130 — interrupted by Ctrl-C.

First-run flow

On a fresh machine, the first thing fred login does is open your browser to https://app.fredcode.net/cli/authorize and start a localhost callback listener on port 41257. The flow is RFC 7636 PKCE — the CLI generates a code verifier and challenge, the browser sends you through sign-in (Google, GitHub, email + password, or magic link), and on approval the auth server redirects to http://127.0.0.1:41257/callback?code=… where the CLI exchanges the code for an API key.

The key lands in two places:

  • ~/.config/fred/credentials.json (mode 0600, one row per machine).
  • The macOS keychain, if you installed with the [keychain] extra (pip install 'fredcode[keychain]'). The credentials file then keeps api_key empty and the keychain copy wins on read.

On a headless box (no browser, SSH only), pass --device-code:

fred login --device-code

That swaps to RFC 8628 device flow — the CLI prints a short code, you visit https://app.fredcode.net/activate from any other device with a browser, paste the code, and the CLI polls until approval lands.

Note

Legacy DSC_* env vars are aliases of FRED_*. Both are read; FRED_*wins on conflict. Old CI configs keep working — there's no deprecation timeline, and the legacy prefix will stay supported indefinitely.

Where else to look