CLI reference

openllm runs your AI clients through OpenLLM, manages the local daemon, and serves the OpenLLM MCP server. The short alias ollm runs the same binary. It runs on macOS and Linux.

Install it with the one-line installer. See Install for options.

curl -fsSL https://www.openllm.sh/install | bash

Every command accepts -h or --help.

Global flags

OpenLLM's own flags go before the client name. Everything after the client name is passed to the client unchanged, so openllm claude -d passes -d to Claude Code.

Commands

Clients

Session clients (claude, codex, grok, hermes, opencode) apply OpenLLM for one run and never modify the client's own config. The client must already be installed.

The CLI picks the gateway on every launch: your local daemon if it answers, otherwise the hosted gateway, which hands subscription models to one of your online devices. To force one, set OPENLLM_GATEWAY=local or OPENLLM_GATEWAY=cloud.

See Clients for setup guides.

openllm claude

openllm [-d] [--new|--attach [id]] claude [...args]

Runs Claude Code through OpenLLM. Your ~/.claude config is never modified.

• -d adds --dangerously-skip-permissions.
• When Claude Code sessions are already running on this machine, the CLI offers them before starting a new one.

openllm claude --resume

openllm codex

openllm [-d] [--new|--attach [id]] codex [...args]

Runs Codex through OpenLLM. Your ~/.codex/config.toml is never modified.

• -d adds --dangerously-bypass-approvals-and-sandbox.

openllm codex

openllm grok

openllm [-d] [--new|--attach [id]] grok [...args]

Runs Grok Build through OpenLLM. Your ~/.grok config and auth.json are never modified.

• -d adds --always-approve.

openllm -d grok

openllm hermes

openllm hermes [...args]
openllm hermes install | uninstall | status

Runs the Hermes TUI through OpenLLM.

• install writes a sticky openllm profile (for Hermes gateway and cron use) without touching your default config.
• uninstall restores the previous sticky profile.
• status reports whether the sticky profile is wired.
• --no-persist uses a one-run overlay and skips the sticky profile.
• -d adds --yolo.

openllm hermes -z "Summarize this repo"

openllm opencode

openllm [--new|--attach [id]] opencode [...args]

Runs OpenCode through OpenLLM. Your ~/.config/opencode config is never modified.

openllm opencode

openllm chatgpt

openllm chatgpt [--with-chatgpt-auth|--without-chatgpt-auth] [uninstall|status]

Installs an OpenLLM ChatGPT launcher in /Applications. Open it instead of ChatGPT to run the ChatGPT Mac app through OpenLLM. Your chats and ~/.codex are not changed. macOS only; requires /Applications/ChatGPT.app.

• uninstall removes the launcher and everything it wrote.
• status reports whether the launcher is installed.
• --with-chatgpt-auth keeps the app's ChatGPT sign-in (dictation, connectors).
• --without-chatgpt-auth runs the app with no ChatGPT account. Without either flag, the install asks or keeps your previous choice.

openllm chatgpt --without-chatgpt-auth

openllm raycast

openllm raycast [uninstall|status]

Raycast runs continuously, so OpenLLM is applied to its config once. The base URL is your local daemon if it answers, otherwise the hosted gateway, and it stays fixed until you re-run openllm raycast. macOS only.

• With no argument, applies or refreshes the config. Safe to re-run.
• uninstall removes exactly what was applied.
• status reports whether OpenLLM is wired in.

openllm raycast status

One-shot prompt

openllm -p <prompt> [-m <model>] [-s <system>] [--no-stream] [--output-format text|json|stream-json]

Sends one prompt and streams the reply to stdout. Requires an API key.

• -p -, or piped stdin with no -p at all (for example openllm -m lite), reads the prompt from stdin.
• -m, --model picks a model or alias (default ultra).
• -s, --system sets a system prompt.
• --no-stream waits for the full reply.
• --output-format json (or --json) prints one result object with text, model, resolved_model, usage, and attempted_fallbacks. stream-json prints one JSON object per line. In JSON modes, errors print as {"type":"error",…} with exit code 1.

git diff | openllm -p - -m lite

Daemon

The daemon runs subscription and local models on this machine. See Devices.

The daemon is the same binary. The installer also links it as openllmd in ~/.openllm/bin, so commands shown in the app such as openllmd sessions on and openllmd logs work there too.

openllm start

openllm start

Starts the daemon. If no API key is saved, it guides you through sign-in and asks for your sk-llm- key first.

openllm start

openllm stop

openllm stop

Stops the daemon. A stopped daemon doesn't count toward your device limit.

openllm stop

openllm restart

openllm restart

Restarts the daemon, for example after you finish credential setup.

openllm restart

openllm status

openllm status

Shows the daemon's service registration, supervisor state, a live status check, and its file paths.

openllm status

openllm sessions

openllm sessions [list]
openllm sessions attach <id>
openllm sessions kill <id>

Lists, attaches to, or kills the live client sessions on this machine, including ones started from the browser.

• list (the default) shows running sessions.
• attach <id> joins a live session alongside any other viewer.
• kill <id> ends a session.

openllm sessions list

To let the browser open remote terminal sessions on this machine, use openllmd sessions on or openllm login --pty-sessions. They are off after a plain install; Add a device in the dashboard turns them on unless you switch Remote terminal off.

openllm auto-update

openllm auto-update <on|off|status>

Reads or changes whether the daemon updates itself in the background. It is on by default.

openllm auto-update status

Providers & auth

openllm auth

openllm auth <providers|status|usage|refresh|login|submit-code|cancel|logout> [provider] [--json]

Manages subscription sign-ins on this machine through each vendor's own CLI. It does not sign you in to your OpenLLM account.

• providers lists this daemon's providers and their login methods.
• status [provider] [--flow-id <id>] reads sign-in state, or checks a login in progress.
• usage [provider] reads cached usage without refreshing anything.
• refresh [provider] refreshes usage.
• login <provider> [--method browser|device] starts the vendor's sign-in.
• submit-code <provider> --flow-id <id> sends a paste-back code, read from stdin.
• cancel <provider> [--flow-id <id>] cancels a pending sign-in.
• logout <provider> signs out of the provider on this machine.

Starting a login is not the same as a successful sign-in. Check status afterward. See Subscriptions.

openllm auth login claude_code

openllm login

openllm login [--key <sk-llm-…>] [--start] [--pty-sessions|--no-pty-sessions] [--json]

Saves your OpenLLM API key to ~/.openllm/.env, replacing any existing key. Without --key, it reads the key from piped stdin or asks for it with hidden input. A running daemon restarts to pick it up. Create keys on the Devices & keys page.

• --start also starts the daemon when it isn't running.
• --pty-sessions allows remote terminal sessions on this machine; --no-pty-sessions disallows them.
• --json prints {"saved":true,"daemon":…} on stdout.

echo "$OPENLLM_API_KEY" | openllm login --start

openllm config

openllm config --json

Prints the resolved configuration as JSON: gateway origin, env file, daemon port, whether a key is configured, and the key's public id. The secret is never printed.

openllm config --json

MCP & memory

openllm mcp

openllm mcp [--only openllm|openllm-memory]

Runs the OpenLLM MCP server over stdio. It serves gateway tools (openllm) and memory tools (openllm-memory). Requires a configured API key. --only limits it to one group, for debugging. See MCP server and Memory.

openllm mcp

openllm exec

openllm exec memory <recall|extract>

Runs a hook utility. Client hooks use it for automatic memory: recall reads a hook event on stdin, and extract starts background memory extraction. You don't normally run it by hand.

openllm exec memory recall < event.json

Setup & maintenance

openllm setup

openllm setup

Links openllm and ollm onto your PATH (/usr/local/bin or ~/.local/bin), adds a managed block to your shell rc, and installs shell completion. Safe to re-run. If openllm isn't found after install, run ~/.openllm/bin/openllm setup and open a new terminal.

~/.openllm/bin/openllm setup

openllm completion

openllm completion <bash|zsh|fish|install>

Prints a completion script for a shell, or install wires it into your shell config.

openllm completion install

openllm update

openllm update

Updates the whole product: reruns the installer from your configured gateway so the daemon and CLI match. Keeps your env file and does not edit your shell.

openllm update

openllm self-update

openllm self-update

Updates only the CLI binary to the gateway's pinned release, after verifying its SHA-256.

openllm self-update

openllm doctor

openllm doctor [--fix] [--ai] [--model <alias>] [-c]
openllm doctor report [--dry-run]
openllm doctor opt-out | opt-in --yes | reporting-status

Checks the daemon's health and finds leftover install state. Without flags it changes nothing.

• --fix removes OpenLLM-owned leftovers and managed regions. Your own settings in those files are kept.
• --ai adds an AI diagnosis (model lite) that sends the redacted report and recent daemon logs through your gateway. --model <alias> picks another model and implies --ai.
• -c, --copy copies the report to the clipboard.
• report asks the daemon to upload its sanitized diagnostic events. It does not read raw daemon logs. --dry-run previews the export without uploading.
• opt-out, opt-in --yes, and reporting-status control and show diagnostic reporting.

openllm doctor --fix

openllm uninstall

openllm uninstall [--yes] [--keep-logins|--remove-logins]

Removes the daemon and the CLI from this machine. It stops the service, reverses Raycast, ChatGPT launcher, and Hermes wiring, removes the PATH links and shell-rc block, and deletes CLI state under ~/.openllm.

• --yes, -y skips the confirmation. Without it, a terminal is required.
• --keep-logins keeps your subscription sign-ins for a reinstall. --remove-logins removes them (the default with --yes).

openllm uninstall --keep-logins

openllm api

openllm api --spec

Prints the OpenAPI spec embedded in the CLI, the same document the gateway serves at /api/swagger. See API reference.

openllm api --spec > openapi.json

openllm version

openllm version

Prints the CLI version.

openllm version

openllm help

openllm help

Shows the command list, flags, and config variables.

openllm help

Configuration file

The CLI and the daemon share ~/.openllm/.env. Each value is read from the process environment first, then this file.

Environment variables

These are read from the process environment only, not from ~/.openllm/.env.

Last updated on