CLI reference

The real command-line flags, subcommands and slash commands of the theus binary, taken straight from the source.

Run Theus with no arguments to start an interactive session in the current directory. Pass a prompt as the first positional argument to seed the session, or use -p/--print for non-interactive output:

theus                       # interactive session
theus "explain this repo"   # seed the session with a prompt
theus -p "list the tests"   # print the answer and exit
theus --version             # print version and exit

Theus starts an interactive session by default. Use -p/--print for pipe-friendly, non-interactive output. In -p mode the workspace-trust dialog is skipped, so only run it in directories you trust.

Global flags

These flags apply to the default (session) command. Only the most commonly used, non-hidden options are listed here.

Flag	What it does
`-h, --help`	Show help for the command.
`-v, --version`	Print the version and exit.
`-p, --print`	Print the response and exit (useful for pipes). Skips the workspace-trust dialog.
`-d, --debug [filter]`	Enable debug mode, with optional category filtering (e.g. `"api,hooks"` or `"!1p,!file"`).
`--debug-file <path>`	Write debug logs to a specific file path (implicitly enables debug mode).
`--verbose`	Override the verbose setting from configuration.
`--bare`	Minimal mode: skip hooks, LSP, plugin sync, auto-memory, background preloads and keychain reads. Provide context explicitly via the prompt/settings flags.
`--output-format <format>`	Output format (with `--print`): `text`, `json` or `stream-json`.
`--input-format <format>`	Input format (with `--print`): `text` or `stream-json`.
`--json-schema <schema>`	JSON schema to validate structured output against.
`--include-partial-messages`	Include partial message chunks as they arrive (with `--print --output-format=stream-json`).
`-c, --continue`	Continue the most recent conversation in the current directory.
`-r, --resume [value]`	Resume a conversation by session ID, or open the interactive picker with an optional search term.
`--fork-session`	On resume, create a new session ID instead of reusing the original.
`--from-pr [value]`	Resume a session linked to a PR by number or PR URL, or open the picker.
`--model <model>`	Model for the current session. Accepts a configured alias or a provider model id.
`--effort <level>`	Effort level for the session: `low`, `medium`, `high`, `max`.
`--fallback-model <model>`	Auto-switch to the given model when the default is overloaded (with `--print`).
`--agent <agent>`	Agent for the current session. Overrides the `agent` setting.
`--permission-mode <mode>`	Permission mode for the session.
`--dangerously-skip-permissions`	Skip all permission checks. Recommended only for sandboxes with no internet access.
`--allowedTools, --allowed-tools <tools...>`	Allowlist of tool names (comma/space separated, e.g. `"Bash(git:*) Edit"`).
`--disallowedTools, --disallowed-tools <tools...>`	Denylist of tool names.
`--tools <tools...>`	Restrict the available built-in tools (e.g. `"Bash,Edit,Read"`; `""` disables all, `default` enables all).
`--mcp-config <configs...>`	Load MCP servers from files or JSON strings (space separated).
`--strict-mcp-config`	Use only the MCP servers from `--mcp-config`, ignoring other MCP configuration.
`--system-prompt <prompt>`	System prompt to use for the session.
`--append-system-prompt <prompt>`	Append text to the default system prompt.
`--settings <file-or-json>`	Path to a JSON settings file, or a JSON string, to load additional settings from.
`--setting-sources <sources>`	Comma-separated settings sources to load: `user`, `project`, `local`.
`--add-dir <directories...>`	Extra directories tools are allowed to access.
`--agents <json>`	JSON object defining custom agents.
`--session-id <uuid>`	Use a specific session ID for the conversation (must be a valid UUID).
`-n, --name <name>`	Give this session a visible name (shown in `/resume` and the terminal title).
`--ide`	Auto-connect to the IDE at startup when exactly one valid IDE is available.
`--plugin-dir <path>`	Load plugins from a directory for this session only (repeatable).
`--chrome` / `--no-chrome`	Enable or disable the browser integration.
`-w, --worktree [name]`	Create a new git worktree for this session (optionally named).
`--tmux`	Create a tmux session for the worktree (requires `--worktree`).
`--max-turns <turns>`	Maximum agentic turns in non-interactive mode (with `--print`).
`--max-budget-usd <amount>`	Maximum USD to spend on API calls (with `--print`).
`--no-session-persistence`	Disable session persistence: sessions are not saved to disk and cannot be resumed (with `--print`).

Subcommands

Beyond the default session command, the theus binary exposes several subcommands. Run theus <subcommand> --help for details.

Subcommand	What it does
`theus mcp`	Configure and manage MCP servers (`serve`, `list`, `get`, `add-json`, `remove`, `add-from-theus-desktop`, `reset-project-choices`).
`theus auth`	Manage authentication: `login`, `status`, `logout`.
`theus plugin` (alias `plugins`)	Manage Theus plugins: `list`, `install`, `uninstall`, `enable`, `disable`, `update`, `validate`, plus the `marketplace` subgroup.
`theus agents`	List the configured agents.
`theus doctor`	Check the status of the Theus auto-updater and installation.
`theus update` (alias `upgrade`)	Check for updates and install them if available.
`theus install [target]`	Install the native Theus build (`stable`, `latest` or a specific version).
`theus setup-token`	Set up a long-lived authentication token (requires subscription auth).
`theus completion <shell>`	Generate a shell completion script (bash, zsh or fish).

Login is also reachable directly: the launcher intercepts login, signin and entrar and routes them to the Theus sign-in flow.

Slash commands

Inside an interactive session, type / to open the command palette. These are the core built-in slash commands. Type /help at any time to see the full list available in your session (skills and plugins add more).

Session and context

Command	What it does
`/help`	Show help and the available commands.
`/clear`	Clear the conversation history and free up context.
`/compact [instructions]`	Clear the history while keeping a summary in context. Optional summary instructions.
`/context`	Visualize current context usage as a colored grid.
`/resume`	Resume a previous conversation.
`/rewind`	Restore code and/or the conversation to an earlier point.
`/copy`	Copy Theus's last response to the clipboard (or `/copy N` for the N-th most recent).
`/memory`	Edit the Theus memory files.

Model and behavior

Command	What it does
`/model` (alias `/modelo`)	Choose Theus's AI model.
`/effort`	Set the model's effort level.
`/plan`	Enter plan mode or show the current session plan.
`/providers`	Connect local models, your own API keys and custom endpoints.
`/permissions`	Manage the tool permission rules (allow and deny).
`/agents`	Manage agent configurations.
`/skills`	List the available skills.
`/mcp`	Manage MCP servers.

Inspect and diagnose

Command	What it does
`/status` (alias `/estado`)	Show Theus status: version, model, account, API connectivity and tools.
`/cost`	Show total cost and duration of the current session.
`/usage`	Show your plan's usage limits.
`/diff`	Show uncommitted changes and per-turn diffs.
`/review`	Review a pull request.
`/doctor`	Diagnose and verify your Theus installation and configuration.
`/init`	Initialize project instruction file(s) and optional skills/hooks from the codebase.

Appearance and account

Command	What it does
`/config`	Open the settings panel.
`/theme`	Change the theme.
`/vim`	Toggle between Vim and Normal editing modes.
`/login`	Sign in to your Theus account.
`/logout`	Sign out of your Theus account.

This page lists real flags and commands from the current build. Some options are gated by feature flags or account type and may not appear in every install; the authoritative list for your version is always theus --help and /help.

Theus — local-first multimodel coding agent · Made in Peru