Skip to content

CLI Reference

Run centaur --help for the everyday path and centaur <command> --help for one command. Specialist commands are hidden from ordinary help to reduce choice overload, but remain callable and are all listed here.

Command Description
centaur "<outcome>" Select context and prepare the preferred AI destination
send Choose a chat or browser explicitly
task Prepare context without opening a chat
headless (context alias) Return workspace context without touching the clipboard, browser, or Explorer
data Export explicitly selected datasets
db profile Inspect aggregate database shape without returning rows
init Set up the current project for Codex and Claude Code
install, mcp, skill, browser Configure integrations
doctor Check the installation
companion Open or manage the native Windows outcome window
check Show and optionally run project checks under supervision
worktree Manage isolated Git worktrees
metrics (stats alias) Inspect prepared-context estimates by file and destination
results, result Search, capture, and reopen saved local replies
continue Prepare a full or explicitly acknowledged delta continuation
audit Scan the workspace for likely leaked credentials
ui Open the interactive workspace menu
--export Export context and prompt for manual upload
--clipboard, --file, --stdin Review and apply patches
undo, history Revert or list patch sessions
config, prompt, update Configure or update Centaur

centaur metrics shows locally recorded handoffs, estimated prepared tokens, destination totals, and files that contribute repeated context. Use specific paths or --mode changed when the task needs only those files. These counts can help trim future handoffs; they do not measure provider bills, tokens avoided in another session, or whether a prepared handoff was sent.

centaur metrics --format json includes measurement_basis. For compatibility, the legacy host_input_tokens_saved key still contains the estimated project context, excluding Centaur’s instructions. Its name does not establish savings. estimated_cost_saved_usd, total_cost_saved_usd, and context_headroom_preserved_pct now return null because those values are unknown. JSON consumers must handle null rather than expect a number. Existing ledgers retain their counts; old dollar and headroom projections are ignored.

Available in the updated development build; these commands are not yet in a new public installer.

Terminal window
# Search task titles, destinations, and saved reply text
centaur results "parser"
# Save a completed reply against its original full handoff ID
centaur result HANDOFF_ID --file reply.txt
# Read a compact return packet, or explicitly request the complete reply
centaur result RESULT_ID
centaur result RESULT_ID --full
# Default: refresh the full original selection and current project rules
centaur continue --from HANDOFF_ID --chat "chatgpt/account/conversation" "Check the revised parser"
# Only if this same conversation still has the full base context
centaur continue --from HANDOFF_ID --chat "chatgpt/account/conversation" --acknowledge-context "Check the revised parser"

The result packet includes a bounded verbatim excerpt, source freshness, and actual capture/review status. A truncated excerpt is not a substitute for the full evidence. Checks are marked unrecorded unless that result contains check evidence. Saving a reply never approves applying it.

Continuations print prepared context without opening a browser or sending it. They list deleted files, refresh project instructions, and redact likely credentials. Delta mode falls back to full context when acknowledgement is missing, the recorded chat differs, the redaction policy changed or is unknown, or the base was compact. Masked files are refreshed even when unchanged. The scope remains the original selected files plus current project instructions; start a new task to include new source files. The chat identity and acknowledgement are your assertions, not proof of provider memory. Review before pasting.

Describe the outcome. Centaur selects task-specific files within the context budget, uses the chat you chose the first time, and prepares the handoff:

Terminal window
centaur "Refactor parse_patch in src/lib.rs"
# Optional outcome overrides
centaur "Audit the login flow" --redact
centaur "Review the entire project" --full
centaur "Reduce repeated context" --mode compact --browser firefox
centaur "Export receipt for CI or scripts" --format json

Centaur prints a receipt with the selected files, reasons, token estimate, and budget omissions. Applicable project rules are required context, so they remain in the packet even when they take it slightly over budget. It prepares the chat but never presses Send. Review the message and send it yourself.

On the first interactive hand-off, Escape cancels before any browser or app opens. A --browser value remains a one-run override; only a browser chosen in the setup question is saved.

Use send when you want to override the destination. Attachment and paste steps depend on your platform:

Terminal
# Explicit target (chatgpt, claude, gemini, qwen, kimi, deepseek)
centaur send "Add unit tests for error cases" --to chatgpt
# A web chat without an API key
centaur send "Review the parser" --to qwen
# Explicit browser: the same chat is a different account in each one
centaur send "Add unit tests for error cases" --to chatgpt --browser chrome
# One smaller context packet without changing Claude's saved budget
centaur send "Review the parser" --to claude --context-tokens 64000
# Guided task with a chat handoff
centaur task "Optimize database queries" --send
# Make the default redaction explicit
centaur send "Audit auth flow" --redact

Project-context copies mask likely credentials by default. Source files are never changed. Use --no-redact only when a specific handoff must retain raw values; the JSON receipt reports the effective redacted value.

Qwen, Kimi, and DeepSeek open their official web chats and leave the complete hand-off on the clipboard. Paste it into the chat and choose the model there. Centaur does not call their APIs or select a model. Web free-tier limits and API billing are controlled by each provider: Qwen Studio, Kimi, and DeepSeek.

On Windows, create a named custom site in Settings > Websites. From any terminal:

Terminal
centaur config site add team-chat https://ai.example.com/chat --browser edge --default \
--url-template "https://ai.example.com/chat?prompt={prompt}" \
--composer-selector "#chat-input" \
--reply-selector ".assistant-message" \
--action-bar-selector ".action-bar"
centaur config site list
centaur send --site team-chat "Review the billing change"

That creates the same declarative settings you can edit directly:

config.toml
[chat]
default_target = "team-chat"
[sites.team-chat]
url = "https://ai.example.com/chat"
browser = "edge"
url_template = "https://ai.example.com/chat?prompt={prompt}"
composer_selector = "#chat-input"
reply_selector = ".assistant-message"
action_bar_selector = ".action-bar"

Centaur accepts only HTTPS landing pages. It opens the configured page and puts the complete hand-off on the clipboard, but does not synthesize input on a page whose composer identity it cannot verify. Named sites also appear in the Windows tray target list, and default_target makes one available to the outcome-first command and companion. The native Options window and the CLI use this same file. Remove one with centaur config site remove team-chat; if it was the default, Centaur safely returns to auto.

Centaur packages your context into .centaur/export/centaur_context.txt, with the task instructions and output contract embedded at the top. Later sends and exports exclude this generated attachment, even outside a Git repository, so previous context is not packed again.

What happens next depends on the platform:

  • macOS switches to your active conversation tab without refreshing or opening a blank session, attaches the file, and pastes the task prompt beside it.
  • Windows normally opens the selected browser and copies the complete bounded hand-off for one deliberate paste. Existing browser tabs can expose stale hidden chat documents as focused, so the normal path does not type into them. The opt-in ChatGPT desktop app still uses verified UI Automation. The --one-enter path below and dispatched desktop research can submit after checking the destination and complete request.
  • Linux puts the whole payload on the clipboard and opens the chat. One Ctrl+V pastes the task and the code together.

On Windows, centaur send --to chatgpt --wait "Fix the login crash" can watch for the completed browser reply after you send the message. It parses and validates the reply locally, then waits for Enter in the terminal before writing. Typing anything else leaves the plan pending; centaur browser pending shows the exact diff. A timeout is reported as a failure, and the manual clipboard path remains available. Browser reply capture does not work on macOS or Linux yet. It does not press Send for you.

Hands-free ChatGPT on Windows. Run this once and sign in to ChatGPT in the window it opens, then close it:

Terminal window
centaur browser signin

From then on a plain centaur send --to chatgpt "Fix the login crash" attempts the round trip: it opens a new chat in Centaur’s own Chrome profile off-screen, verifies the page and composer, enters the complete request, invokes Send, confirms the submitted message, and watches that same chat for a finished reply. Sign-in, website verification, and supported page controls are required. To force this path, or to use Qwen in Firefox, add --one-enter:

Terminal window
centaur send --to chatgpt --browser chrome --headless "Fix the login crash"
centaur send --to chatgpt --browser chrome --one-enter "Fix the login crash"
centaur send --to qwen --browser firefox --one-enter "Fix the login crash"

With Chrome there are two ways in, and Centaur picks for you:

  • Centaur’s own Chrome profile (no prompts). Run centaur browser signin once and sign in to ChatGPT in the window it opens. After that, sends run in that profile off-screen: nothing appears, nothing asks for permission, and the window closes when the reply is captured. If a CAPTCHA or security challenge appears, the browser window is brought to the front so you can complete verification, and then resumes automatically.
  • Your own Chrome. Without that sign-in, Centaur uses your signed-in Chrome 144 or newer. Turn on remote debugging once at chrome://inspect/#remote-debugging. Chrome asks you to Allow each new connection, so keep the companion running (centaur gui): it holds one connection and you click Allow once per session instead of once per send. The companion only ever offers the CLI one thing, sending a prompt to a new ChatGPT tab and returning that tab’s text, never general control of your browser. Centaur opens one background ChatGPT tab and watches its assistant answer until generation stops and the text settles. Network events provide extra error detection; capture does not require a particular reply endpoint. The tab closes after capture, or comes to the front if something fails. A leftover Centaur hand-off in ChatGPT’s saved draft is replaced; any other draft stops the send. Qwen in Firefox uses a visible new window; keep it open. Centaur stops without sending if it cannot prove the page, sign-in, composer, complete entered text, or unique Send button.

After pressing Send, the Chrome runner reports success only when the composer clears and the complete request appears as a submitted user message. If confirmation fails, inspect the opened chat before retrying: the request may already have been sent. A successful centaur doctor checks local storage, settings, and MCP configuration; it does not verify browser sign-in or a live AI round trip.

By default it never changes files on receipt alone. The validated diff is shown in the terminal and a notification says a patch is ready: press Ctrl+Alt+Enter from any app within two minutes, or Enter in the terminal, to apply it with an undo snapshot. Typing anything else, or waiting, leaves the plan pending. Add --auto-apply to skip that step: the validated patch is applied as soon as it is captured and a notification reports the result, with centaur undo to revert. --headless and --one-enter cannot be combined with --wait, --followup, or --zip. They are not supported for custom sites, other browsers, macOS, or Linux.

On a platform that attempts an attachment, failure falls back to the payload-as-text path rather than sending nothing. Windows browser handoffs use text deliberately. --format json reports the result in attachment_on_clipboard.

Open the interactive workspace menu:

Terminal window
centaur
centaur ui

Open the native Windows outcome window, register it for sign-in, inspect its state, or stop it:

Terminal window
centaur gui
centaur gui --autostart
centaur gui --status
centaur gui --stop

centaur companion remains an equivalent long form. The window uses the same planner as centaur "...". Its temporary handoff copy is always redacted because there is no terminal prompt for credential warnings. Code, Research, and Manual are visible route choices. Manual prepares a handoff for you to send. Code and research capture submit the reviewed task and return its reply. Code requires selected project files, while research accepts a question without files. Results opens the native reader and Settings opens sidebar preferences. Patches still require review before application. This redesigned interface requires the current development version.

Show project checks, then run them only after inspection:

Terminal window
centaur check
centaur check --run
centaur check --run --repair

--repair acts only after a failure. It prepares one redacted handoff containing the tracked original request, the files changed by the latest Centaur update, and at most 6,000 characters of check output. It never presses Send or applies another patch, and the check keeps its failure exit status. JSON and MCP verification results include the same repair_task and repair_paths fields without opening a chat.

Scan the workspace for likely leaked credentials:

Terminal window
centaur audit

Check the installation. Use the second form before sharing the output:

Terminal window
centaur doctor
centaur doctor --redact-paths

Doctor requires an existing workspace directory, verifies that Centaur’s storage and undo-history directories accept writes, and checks that settings can be read and parsed. Its temporary storage probes are removed after checking. Failed checks include a repair hint; existing files and malformed settings are preserved.

Return task-specific context for a script or local agent without opening a window or changing the clipboard. JSON is the default:

Terminal window
centaur headless --task "Refactor parser"
centaur headless --task "Refactor parser" --paths src/lib.rs tests
centaur headless --task review --format text
centaur context --task "Review parser.rs" --context-tokens 8000

centaur context remains an alias for existing scripts. The JSON result includes the context plan: selected files and reasons, estimated size, budget, relevant omissions, and packed context. Text format emits only the packed context.

Development builds add --context-tokens N to context/headless for a one-run selection budget from 1 to 10,000,000 estimated tokens. It applies to ordinary output, --zip, and --run, without changing saved settings. The older centaur --context-tokens N context ... placement also works; a budget after the subcommand takes precedence. Budget pruning does not remove explicit paths or applicable repository instructions; existing export filters still apply. Packing headers can also exceed the estimate, so this is not a hard model limit. Non-ZIP JSON exports include token_warning when the estimate exceeds the budget.

Development builds also preserve repeated blank lines in ordinary source text so exported SEARCH text can match the workspace. Redaction, data excerpts, compact summaries, and large-file segmentation still have their documented limits.

To use the experimental one-Enter sending and reply-capture route, pass -x or --run. Browser focus or website verification can still require interaction; review returned changes before applying them:

Terminal window
centaur headless -x "Fix the login crash"
centaur context --run "Refactor parser" src/lib.rs

This context-only command is separate from the Windows send --wait and experimental send --one-enter web-chat flows. Without --run, headless does not send anything to a browser. The one-Enter mode uses a dedicated chat tab or window with identity and content checks; it is not a background web API.

Centaur recognizes common repository rules automatically: AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md, and .github/instructions/*.instructions.md. GitHub instruction files with an applyTo glob are included only when that glob matches a selected file. The receipt labels every rule it carried.

When an interactive query is materially ambiguous, Centaur asks one focused question and replans with the answer. JSON and other non-interactive callers receive status: "clarification_needed" instead of a guess or an oversized export.

Requests such as “send this to Centaur” need an actual objective. Headless mode returns a clarification with zero files, including with --zip, without preparing an archive or opening a browser. Add the task to the next invocation, for example centaur headless --task "Review parser.rs for invalid input handling".

Create upload-ready context files and copy the workflow prompt:

Terminal window
centaur --export

The guided centaur task "..." form also records the selected files and adds a short workspace tag to its copied or saved prompt. If the AI repeats that tag, Centaur refuses the reply in any other project. A plain --export without a task remains an untracked context export.

Limit the export to selected paths:

Terminal window
centaur --export src tests/parser.rs

Let Centaur choose between current changes and the full project:

Terminal window
centaur task "Fix issue #42"

Force a guided task to use the full project:

Terminal window
centaur task --full "Fix issue #42"

Project-context copies redact likely secrets by default. Override that behavior for one run only when the raw value is required:

Terminal window
centaur task --no-redact "Fix issue #42"

Choose a direct export mode:

Terminal window
centaur --export --mode changed
centaur --export --mode staged
centaur --export --mode compact

Add an explicit task to a direct export:

Terminal window
centaur --export --task "Fix issue #42"

The same one-run override works for direct exports:

Terminal window
centaur --export --no-redact

full is the default for direct exports. Invalid mode names are rejected; they never fall back to a full export. Changed and staged modes include common project manifests so the model still receives build context. Deleted files are omitted because there is no remaining content to upload.

Copy explicitly selected datasets in their native format and prepare an analysis prompt:

Terminal window
centaur data data/games.csv data/quotes.jsonl --task "Check missing timestamps and joins"
centaur data "data/player stats.parquet" --no-clipboard
centaur data data/events.json --redact

The Analyze data menu item offers the same workflow. Enter one workspace-relative file per line. Named files may be gitignored; folders, paths outside the workspace and duplicate selections are refused. Supported extensions are .csv, .json, .jsonl and .parquet. Text files must be UTF-8 (a BOM is preserved).

The new local folder contains numbered native copies, DATA_MANIFEST.json and START_HERE.txt. Upload the copies and manifest, then paste the prompt from the clipboard or START_HERE.txt. Centaur does not upload files or fetch database records. With --no-clipboard, the clipboard is untouched. Existing export settings control prompt copying and opening the folder.

Without redaction, the copies preserve all source bytes. The manifest records source-relative paths, original/exported byte counts and SHA-256, plus any redaction. Rows and schema remain explicitly unknown until the analysis tool parses the files. Sources are never modified. Text credentials detected by the existing scanner block export unless --redact is requested; that scan is not a complete privacy audit. Binary Parquet is copied without parsing or scanning, and cannot use --redact.

Local bounds are 20 files, 50 MiB per file and 200 MiB combined. These are Centaur bounds, not ChatGPT upload limits. ChatGPT’s supported formats vary by account and analysis environment; Parquet support is not guaranteed. Centaur does not convert, sample or split data files. Remove the temporary folder yourself when finished.

Set DATABASE_URL for Postgres or Supabase, or MONGODB_URI for Mongo, then run:

Terminal window
centaur db profile --engine postgres --redact
centaur db profile --engine mongo --sample 500 --format json --redact

Choose Database profile under More tools for the guided terminal version. Centaur uses the installed psql or mongosh client and never stores the connection string. The output is aggregate schema and distribution data, never database rows. Use --url-env NAME to read a different environment variable.

Read a complete patch response from the clipboard, a UTF-8 file, or standard input:

Terminal window
centaur --clipboard
centaur --file response.txt
centaur --stdin < response.txt

The expected block format is:

Patch Format
File: src/example.rs
<<<<<<< SEARCH
fn old() {}
=======
fn new() {}
>>>>>>> REPLACE

To create a file, leave SEARCH empty:

Create File Format
File: src/new_file.rs
<<<<<<< SEARCH
=======
fn brand_new() {}
>>>>>>> REPLACE

To delete code, leave REPLACE empty.

Search text should include enough surrounding context to match exactly once. Before writing, Centaur validates the complete payload. Malformed blocks and ambiguous or unsafe paths are rejected.

The interactive workflow shows a deterministic summary and the exact computed diff before a default-no confirmation. It also rejects source files changed after review.

If a later filesystem write fails, Centaur uses the undo snapshot to restore files already written. If recovery fails, the error names the exact snapshot command to run after inspecting the workspace.

An exact NO_CHANGES response is a successful no-op.

--dry-run performs the same planning and rendering without modifying the workspace or history:

Terminal window
centaur --dry-run --clipboard

Piped input cannot answer an interactive prompt. Use --yes only after reviewing the producer and payload, or use --dry-run for a side-effect-free check:

Terminal window
generate-centaur-patch | centaur --stdin --dry-run
generate-centaur-patch | centaur --stdin --yes

The optional local Ollama fallback can repair unmatched blocks, but its output still passes through the deterministic planner and one transactional write:

Terminal window
centaur --llm auto --clipboard --yes

Revert the latest session in this workspace, or name an older session:

Terminal window
centaur undo
centaur undo <session-id>

List sessions for this workspace:

Terminal window
centaur history

Set up the current project for Codex and Claude Code and add .centaur/ to .gitignore:

Terminal window
centaur init
centaur init --force

Configure supported MCP clients and their commands or skills:

Terminal window
centaur install --client codex
centaur install --client claude-code

Configure one MCP client or run the workspace-scoped stdio server:

Terminal window
centaur mcp install
centaur mcp serve --workspace <path>

Install a Centaur command or skill:

Terminal window
centaur skill install

For agent delegation, development builds add delegate and get_job: prepare bounded context once, optionally dispatch a supported browser job, and retrieve a compact result by ID. See the agent workflow and dispatch requirements.

The MCP server exposes get_context, prepare_handoff, preview_patch, get_pending_review, apply_patch, and undo over either local stdio or authenticated Streamable HTTP. get_context accepts an optional task (or outcome description) to automatically plan and select targeted context for the requested work, alongside mode and paths. prepare_handoff does not send. apply_patch accepts only a workspace-bound plan_id returned by preview_patch.

For ChatGPT web, use OpenAI Secure MCP Tunnel and configure its local stdio command as:

Terminal window
centaur mcp serve --workspace <path>

Create, list, or remove a task worktree:

Terminal window
centaur worktree create <task-id>
centaur worktree list
centaur worktree remove <task-id>
centaur worktree remove <task-id> --force

--force permits removal when that worktree has uncommitted changes. Inspect the worktree before using it.

Create the default configuration or print its location:

Terminal window
centaur config init
centaur config path
centaur config redaction
centaur config redaction off
centaur config history
centaur config history --keep 25
centaur config destination claude --context-tokens 80000

Defaults:

config.toml
[export]
redact_by_default = true
copy_prompt = true
open_export_directory = true
prompt_mode = "first"
max_attachments_per_message = 20
max_attachment_chars = 5000000
context_token_budget = 200000
default_scope = "auto"
[chat]
default_target = "auto"
default_browser = "default"
[history]
completed_handoff_limit = 50
[research]
summary_chars = 800
instructions = ""
return_format = "compact"
[companion]
send_mode = "review"
show_progress = true
notifications = true
always_on_top = false

redact_by_default protects project-context handoffs, headless output, and classic exports. --redact and --no-redact are one-run overrides. Data exports and database profiles retain their own explicit redaction controls because Parquet cannot be scanned or rewritten.

In development builds, [research] sets the requested summary length, extra instructions, and default agent return ("compact" or "full"). Summary length accepts 100–10,000 characters. The desktop Research settings and MCP update_settings edit these same future defaults; research_options on delegate overrides one task. Prepared tasks retain their original options.

[companion] controls the Windows companion and desktop agent dispatch. The default send_mode = "review" asks you to confirm a prepared agent job. Opt-in "automatic" sends an authorized dispatched desktop job without Enter; a prepare-only request remains local. Jobs snapshot all four preferences when prepared. A typed task still requires context review and an explicit send action, and browser focus can still be needed for native sending.

show_progress = false hides automatic-job progress and hides a reviewed job’s window after sending. Its review confirmation remains visible until then. notifications = false suppresses routine notifications; errors still notify. always_on_top controls the project window and capture strip. These controls appear together in the Companion settings section. Its reset stages only companion defaults. Save validates and persists all staged sections, while Cancel discards them. MCP update_settings accepts a partial companion object, such as {"companion":{"send_mode":"automatic"}}; invalid updates leave the current settings intact. Automatic mode does not apply patches or retry failed or uncertain sends.

default_scope accepts "auto" or "full". Automatic scope uses current Git changes as the fallback for a broad outcome; full scope lets the planner search the whole project. Direct task matches still win. For one run, use --full or set --mode changed on the outcome or context command. The Windows Settings > Context section edits this same setting and the token budget.

Interactive choices are saved separately when needed:

config.toml
[chat.browsers]
chatgpt = "chrome"
claude = "firefox"

The older default_browser setting remains the fallback for entries you have not chosen.

Chats and saved websites can also override the shared context limit:

config.toml
[export.context_token_budgets]
claude = 80000
team-chat = 32000

Run centaur config destination NAME to inspect a destination, --context-tokens N to set its limit, or --inherit to use the shared limit again. In Windows Options, choose the destination and leave its budget blank to inherit the Context tab’s default.

Centaur records the task and selected file list so a tagged reply can be tied back to the right workspace and a failed check can recover the original request. It keeps the newest 50 records marked applied by default. Prepared and reviewed hand-offs stay available, and patch undo snapshots are not part of this limit. Changing the limit with config history --keep cleans older completed records immediately; each completion and later hand-off enforce it again. Use --keep 0 to discard completed records.

Set CENTAUR_HOME to keep configuration, prompt templates, and history in a portable or isolated directory.

Manage workflow prompt templates:

Terminal window
centaur prompt show
centaur prompt copy
centaur prompt edit --single
centaur prompt edit
centaur prompt reset

Custom templates should preserve these placeholders where applicable:

{{SESSION_ID}}
{{TOTAL_PARTS}}
{{TOTAL_BATCHES}}
{{USER_TASK}}

The built-in templates instruct the model to answer questions or architectural requests directly in Markdown, emit code modifications using Centaur Search/Replace blocks, and report NO_CHANGES when requested edits are not needed or justified.

centaur prompt reset removes both custom templates and restores the defaults.

Reinstall the latest public release:

Terminal window
centaur update

The updater downloads the same checksum-verified platform archive used by the public installer and replaces Centaur in its current install directory. It does not build the current project or require repository access.

Website privacy