CLI commands

Run orek commands in your terminal. Slash commands such as /context run inside Orek instead. Add --help to any command to see all of its arguments:

orek --help
orek index build --help

Replace angle-bracket placeholders with your own values; sample paths and provider IDs must exist on your machine.

Bare orek and orek chat open the interactive TUI; see TUI commands and keyboard shortcuts for work inside it. Use orek run for a single task from a script or terminal.

Global flags

--reasoning-replay applies until the process exits, so you can compare both methods by running two processes side by side:

orek run --reasoning-replay preserve "review the retry policy, then fix what you find"

For saved settings and which value wins, see Configuration.

Conversation

orek chat

Start an interactive, multi-turn session.

orek chat
orek chat --continue
orek chat --resume <session-id>
orek chat --no-tools

A saved session can be open in only one Orek process at a time. Resuming a session that is already open reports an error instead of starting an unsaved copy. The session becomes available again when that process exits, even if it was killed. See Manage sessions.

orek run

Run one task and exit when it finishes or reaches a limit. Tools are enabled, and changes apply according to the approval mode:

• default asks before edits in an interactive terminal. When standard input is not a terminal, the first approval request fails the run.
• auto_review, yolo, and saved always-allow rules apply matching changes without asking. With fish or another shell that is neither POSIX-compatible nor PowerShell, only yolo runs shell commands (and run_python input commands) without asking.
• plan returns a proposed plan without changing anything and needs no terminal.

A tool call that a permission rule or an approval denies ends the run as a failure.

orek run "explain the retry policy in this project"
orek run --approval-mode auto_review "add a regression test for the retry policy"
orek run --detailed "investigate the failing test"
orek run --json "summarize src/lib.rs"
orek run --json --resume <session-id> "continue from the last finding"
orek run --json --output-schema schema.json "extract the public API"

Each run is saved as a session when possible; if Orek can’t create one, it says so on standard error and reports session_id: null.

When the run ends, Orek saves the conversation, retrying once. If that fails, it saves it as a new session, reports that session_id, and prints the orek run --resume <id> "<prompt>" command to continue it on standard error. If that also fails, session_id is null and the note says why. Either way the result and exit code are unchanged, and the note follows the answer, summary, or JSON object.

If subagents are still working when the main agent answers, the run stays open. Each finished subagent or subagent message wakes the main agent for another turn (shown as [woken by agent `reviewer` (id `ab12`) finished]), and the last answer becomes the run’s final answer. When the run ends, any remaining subagents stop and any running workflow pauses so you can resume it later.

Pressing Ctrl+C stops the current turn and its subagents, saves the conversation and token usage so far, and exits with a nonzero code. In --json mode the result has status: "failed" and the error orek run was interrupted. Pressing Ctrl+C again exits immediately.

JSON output

The JSON object reports:

A failed result can still include a partial final_response and the usage from this run. When you resume a session, earlier answers and usage are not reported again. A saved answer that failed, was cut off, or was interrupted starts with a bracketed notice on its own line, such as [Provider response failed; this saved answer may be incomplete.]; the model never sees this notice.

--output-schema FILE checks final_response, not the whole JSON object. An invalid schema fails before any model request. If the first answer doesn’t match, the model gets one chance to correct it; that correction turn can’t run tools, so the model answers in text. The schema’s $schema selects the JSON Schema version (Draft 7 by default, or Draft 2020-12 when declared). format values such as date and email are enforced, and $ref must point inside the schema file.

Index & retrieval

orek index

Build and inspect the project index that powers symbol lookup, code relationships, and automatic retrieval.

orek index build
orek index build --watch
orek index status
orek index repair --dry-run
orek index query "where is retry behavior implemented?"

The index lives in .orek/index/.

query --json prints an orek.index-query/v1 document with config, diagnostics, snapshots, and the delivered results. --limit caps snapshots only; --limit 0 still returns delivered results. Paths are relative to the project. In source_span, byte offsets exclude the end and line numbers start at 1 and include both ends; approximate matches have a null span, and a graph line_range is null when it can’t be resolved. status: "unavailable" means the index is out of date; a search that finds nothing still reports status: "success".

See Find and explore code for embedding setup and retrieval settings, and Code graph for relationship queries.

Configuration

orek config

Inspect your settings or change supported keys.

orek config show
orek config path
orek config get providers.anthropic.api_key
orek config set ui.theme dark
orek config set providers.openai.api_key '${OPENAI_API_KEY}'
orek config unset providers.openai.api_key_ref --delete-secret
orek config init

Output hides credentials. get reads any setting; set and unset work only on the keys that /config lists inside Orek. For table settings, edit the file that config path prints. set routing.pinned_model requires a model from the catalog, and set routing.pinned_provider requires a configured provider that serves at least one catalog model. init creates .orek/config.toml.

orek setup

Choose a provider, credential, model, theme, and where to save settings.

orek setup
orek setup --provider ollama
orek setup --yes --provider openai --model openai/gpt-6-luna --api-key-stdin

Pass the key for the last command through standard input; there is no --api-key flag. Keys you type or pipe in are stored in your operating system’s credential store. If Orek finds your key in an environment variable, it saves a ${VAR} reference instead. --yes never prompts; unless you specify otherwise, it uses theme auto, saves settings to the project, and saves the API key to your user settings. See Quickstart.

orek skills

List active skills, find skills from other tools, or import one.

orek skills list
orek skills discover
orek skills discover --json
orek skills import cursor.project:review
orek skills import cursor.project:review --scope project

Replace the candidate ID with one that discover returns. Discovering skills doesn’t activate them or change skills.search_paths. See Use skills.

orek mcp

Manage MCP servers, consent, and credentials. These examples assume the named server or local script exists:

orek mcp list
orek mcp add db --scope project -- ./scripts/db-mcp
orek mcp add linear --url https://mcp.linear.app/mcp --oauth
orek mcp add api --url https://api.example.com/mcp --bearer-token-env API_TOKEN
orek mcp test linear
orek mcp auth linear
orek mcp logout linear
orek mcp remove db
orek mcp remove linear --delete-credentials
orek mcp credentials orphans
orek mcp credentials clean-orphans
orek mcp reset-consent

add saves to your user settings unless you pass --scope project, which writes .orek/config.toml. Project servers need your consent before they first connect; test asks for it, connects, lists the server’s tools, and disconnects. logout revokes and removes stored credentials; reset-consent clears your consent for every project MCP server. See MCP setup.

orek lsp

Check language-server diagnostics and manage which servers you trust. Set lsp.enabled and trust a server before expecting it to start.

orek lsp status
orek lsp servers
orek lsp add rust-analyzer --scope project --command rust-analyzer --language-id rust --extension rs --root-marker Cargo.toml
orek lsp trust rust-analyzer
orek lsp trust rust-analyzer --confirm
orek lsp check src/lib.rs
orek lsp restart
orek lsp revoke rust-analyzer
orek lsp reset --confirm
orek lsp remove rust-analyzer --scope project

Without --confirm, trust shows a preview and the command that confirms it. Adding a server doesn’t trust it. Trust is recorded in lsp-consent.json in your user data folder, outside the project. Orek includes settings for 16 language servers; each still needs its program installed and your trust.

Inside Orek, /lsp shows status and handles trust, revoke, reset, and restart. See Language servers and Language-server containment.

License activation

orek license

Activate, inspect, and manage your Orek license, online or offline. Model provider keys are separate.

orek license activate
orek license activate --device-name "Work laptop"
orek license request --output activation-request.json
orek license replace-installation --output replacement-request.json
orek license import --code-file signed-license.txt
orek license import --code-stdin
orek license status
orek license status --json
orek license status --online
orek license migrate
orek license login --no-browser
orek license account --no-browser
orek license buy --no-browser
orek license refresh-paid
orek license sync-revocations
orek license pending-clear
orek license remove-local
orek license deactivate

request, import, status without --online, and remove-local work completely offline. Orek checks your saved license on this machine at startup; it never needs to check in online. If a trial expires during a turn, the work in progress finishes before new model or tool calls stop. See License activation.

Updates

orek upgrade

Check for, install, or roll back an Orek release. update is an alias for this command.

orek upgrade --check
orek upgrade --check --json
orek upgrade
orek upgrade --channel public-beta
orek upgrade --major 2026
orek upgrade --force
orek upgrade --rollback

--check prints your version and the newest release available to you, without downloading anything. It exits 0 when Orek is up to date and 10 when an update is available. --check --json prints one JSON object instead: current_version, latest_version, channel, major, and update_available. A failed check exits with its own code from the table below, so read the code, not just nonzero, in a script.

Without --check, Orek downloads the release from https://orek.ai/api/downloads as a streamed, resumable download (<cache_dir>/upgrade/<artifact>.part, resumed with an HTTP Range request when interrupted; a complete, verified .part left by a failed attempt is reused without a new request), checks its size and SHA-256 digest, backs up the current program to orek.bak and the files installed with it, replaces them, and checks that the new version and its local-model runtime start. If that check fails, Orek restores the previous files. The archive is deleted after a successful install. The upgrade also downloads missing or updated default local models. --force reinstalls even when you are up to date. Without --force, when the selected release equals the running version, Orek checks only the files listed in .orek-installed-companions and repairs missing ones by reinstalling the same version; no runtime self-test runs on an up-to-date install (orek doctor diagnoses it, --force reinstalls it). Orek never downgrades: when the selected release is older than the running version, it exits 50 instead. --rollback restores the previous program and its files offline. If other Orek sessions are still running from the same install, Orek prints a warning on stderr and continues; restart those sessions after the upgrade.

orek upgrade (and the hidden orek self-install used by the installer scripts) exit with distinct codes:

--channel selects stable (default), public-beta, or rc. --major chooses a major version your license covers. --manifest-url (or the OREK_RELEASE_MANIFEST_URL environment variable) points Orek at another release catalog (HTTPS, or HTTP on your own machine). Upgrading replaces only the program and the files installed with it; your settings, sessions, credentials, license, and indexes stay in place. See Upgrade Orek.

Routing & models

orek routes

List your routes and test which one a prompt’s keywords match.

orek routes list
orek routes test "explain the retry policy"

The list combines built-in, user, and project routes. test checks keyword matching only, so a real turn can still choose differently. See Routing.

orek models

Browse the built-in model catalog and the models you add with [[models]].

orek models
orek models --plain
orek models --json

In an interactive terminal this opens a catalog browser; otherwise it prints text. --json prints one orek.models/v1 document. Models are named with their provider, such as openai/gpt-6-luna. The catalog ships with Orek; there is no command to refresh it.

orek providers

Set up provider connections and check that they work.

orek providers
orek providers setup
orek providers setup openai --api-key-stdin
orek providers setup openai --clear-credential
orek providers setup openai --clear-credential --delete-secret
orek providers setup private --yes --credential-store none --base-url http://127.0.0.1:8080/v1 --model-id local-model --context-window 32768
orek providers check

The local example needs a compatible server and model at that address. A key can be stored in your operating system’s credential store, in plain text in the config file (with a warning), as a ${VAR} environment reference, or not at all. A provider with a name of your choosing connects as an OpenAI-compatible server (provider_type = "openai_compatible") and adds its model to the catalog.

orek providers setup [PROVIDER] saves only the provider and its credential; your pinned model and provider stay as they are. Inside a running session, use /setup provider <id> so the session reloads right away. check contacts each configured provider. See Quickstart.

Sessions

orek session

List, view, fork, or export saved sessions.

orek session list
orek session list --include-children
orek session show <id>
orek session fork <id>
orek session fork <id> --skip-damaged
orek session export <id>

The list shows full IDs, newest first, with a FIRST MESSAGE preview (- when empty). --include-children adds saved subagent conversations. show <id> prints a saved conversation; fork <id> copies it to a new session (with an optional --title <TITLE>); fork <id> --skip-damaged builds a new session from the lines of a damaged conversation that can be read and reports how many were lost; export <id> writes it as JSONL, including subagent conversations (--format jsonl, --output <PATH>), leaving out a damaged subagent conversation and naming it.

Inside Orek, use /sessions (alias /resume) to pick a saved session. See Manage sessions.

When you quit Orek, it prints the orek chat --resume <id> command for the session you closed, followed by its /usage table when there was usage.

Observability

Orek sends traces and metrics to an OpenTelemetry (OTLP) collector when observe.otlp_endpoint is set. It has no built-in trace viewer. See OpenTelemetry export.

orek log

Read or clear Orek’s log file.

orek log
orek log --lines 100
orek log --path
orek log --clear

It shows the last 50 lines by default (-n / --lines <N>). --path prints where the log file is; --clear empties it.

Feedback and local support reports

orek feedback

Prepare a local feedback preview with a report ID. Supply only the comment you choose to share; rating is positive, neutral or negative (default neutral). Categories are installation, configuration, reliability, usability, licensing and other (default other).

orek feedback --rating negative --category reliability --comment "Describe the issue"
orek feedback --rating positive --output feedback.json

orek bug-report

Preview a local support report. --output saves the exact JSON preview to a new file and preserves existing files. Neither command uploads anything: review the report, then share it yourself at Contact support with its ID.

orek bug-report
orek bug-report --include-log --output report.json
orek bug-report --doctor-output doctor.txt --output report-with-doctor.json
orek bug-report --clear-crash

Reports include version, compiled source identity, OS/architecture and any pending minimal crash envelope. --include-log opts into the local application log; --doctor-output selects an existing file, without running doctor or contacting providers. Complete inputs up to 1 MiB pass through the shared redactor before the last 32 KiB is selected. Oversized, unreadable and non-UTF-8 files are omitted. Review for private project information before sharing. --clear-crash removes the pending local crash envelope without making a report.

Both commands remain available when a productive license is unavailable. In the TUI, /feedback accepts the same feedback flags and /support shows the contact link. See Support and release limitations.

Multi-agent & IDE

Subagents

There is no subagent command in the CLI. View saved subagent conversations with orek session list --include-children and orek session show <id>, or manage running subagents inside Orek with /agent. See Subagents.

orek acp

Run Orek as an Agent Client Protocol (ACP) agent for your editor. It supports protocol version 1 and the version 2 draft; the editor and Orek agree on one when they connect.

orek acp
orek acp --no-routing

Your editor starts this process and talks to it over standard input and output; there is no network port. --no-routing turns off automatic model routing for the editor’s sessions unless a session turns it back on through its routing option. See Editor integration.

To try the ACP agent from a terminal without an editor, use the built-in test client:

orek acp-client repl --project . --home .orek-acp-home --auto-approve --protocol-version 1

--home DIR gives the agent its own home folder and keeps its Orek data in DIR/.orek-home on Windows and macOS. --auto-approve approves every tool request, so use it only in a project you can afford to change. --protocol-version 1|2 chooses the version the client asks for (2 by default).

Diagnostics

orek doctor

Check your configuration, providers, index, local models, security settings, and the installation itself.

orek doctor

The Installation section reports the install directory, whether that directory is on PATH, any other orek binaries on PATH that would shadow it, the .orek-installed-companions manifest compared with the files on disk, and the orek.bak / .orek-companion-backup backups. It reads only the current executable, the install directory, and PATH; it starts no processes, and it is shown even when the configuration fails to load.

The local inference section shows which llama-server program Orek uses and where it was found, your index.llama_server_device and index.llama_server_gpu_layers settings, the GPUs Orek detected, whether local models are running on the GPU or fell back to the CPU, and whether the embedding, reranking, and auto-review models are ready.

The security section shows your saved OS sandbox setting (Sandbox: off, Sandbox: on, or Sandbox: on, held off by OREK_SANDBOX=off), whether the local auto-review model is ready, and, when exec.default_sandbox is not approved, an experimental execution-policy line. The LSP section shows whether language servers are enabled, the project root, containment, configured servers, whether their programs are found, and trust, without starting any server. Output hides credentials, including ones inside URLs. With update.check_on_startup = true, the TUI also checks the release catalog once at startup (cached for 24 hours) and shows an [update vX] status-bar chip plus a notice when a newer release exists in your current major; see Updates.

orek completion

Generate shell completion scripts. These examples write files in the current directory:

orek completion bash > orek.bash
orek completion zsh > _orek
orek completion fish > orek.fish

Install the generated file where your shell expects completion scripts.

See also

• Configuration
• Agent tools
• @ reference syntax