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 Summary
Section titled “Command Summary”| 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 |
Context estimates
Section titled “Context estimates”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.
Saved results and continuations
Section titled “Saved results and continuations”Available in the updated development build; these commands are not yet in a new public installer.
# Search task titles, destinations, and saved reply textcentaur results "parser"
# Save a completed reply against its original full handoff IDcentaur result HANDOFF_ID --file reply.txt
# Read a compact return packet, or explicitly request the complete replycentaur result RESULT_IDcentaur result RESULT_ID --full
# Default: refresh the full original selection and current project rulescentaur continue --from HANDOFF_ID --chat "chatgpt/account/conversation" "Check the revised parser"
# Only if this same conversation still has the full base contextcentaur 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.
Quick commands
Section titled “Quick commands”Describe the outcome. Centaur selects task-specific files within the context budget, uses the chat you chose the first time, and prepares the handoff:
centaur "Refactor parse_patch in src/lib.rs"
# Optional outcome overridescentaur "Audit the login flow" --redactcentaur "Review the entire project" --fullcentaur "Reduce repeated context" --mode compact --browser firefoxcentaur "Export receipt for CI or scripts" --format jsonCentaur 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:
# Explicit target (chatgpt, claude, gemini, qwen, kimi, deepseek)centaur send "Add unit tests for error cases" --to chatgpt
# A web chat without an API keycentaur send "Review the parser" --to qwen
# Explicit browser: the same chat is a different account in each onecentaur send "Add unit tests for error cases" --to chatgpt --browser chrome
# One smaller context packet without changing Claude's saved budgetcentaur send "Review the parser" --to claude --context-tokens 64000
# Guided task with a chat handoffcentaur task "Optimize database queries" --send
# Make the default redaction explicitcentaur send "Audit auth flow" --redactProject-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:
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 listcentaur send --site team-chat "Review the billing change"That creates the same declarative settings you can edit directly:
[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-enterpath 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+Vpastes 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:
centaur browser signinFrom 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:
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 signinonce 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:
centaurcentaur uiOpen the native Windows outcome window, register it for sign-in, inspect its state, or stop it:
centaur guicentaur gui --autostartcentaur gui --statuscentaur gui --stopcentaur 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:
centaur checkcentaur check --runcentaur 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:
centaur auditCheck the installation. Use the second form before sharing the output:
centaur doctorcentaur doctor --redact-pathsDoctor 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.
Headless and export
Section titled “Headless and export”Return task-specific context for a script or local agent without opening a window or changing the clipboard. JSON is the default:
centaur headless --task "Refactor parser"centaur headless --task "Refactor parser" --paths src/lib.rs testscentaur headless --task review --format textcentaur context --task "Review parser.rs" --context-tokens 8000centaur 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:
centaur headless -x "Fix the login crash"centaur context --run "Refactor parser" src/lib.rsThis 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:
centaur --exportThe 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:
centaur --export src tests/parser.rsLet Centaur choose between current changes and the full project:
centaur task "Fix issue #42"Force a guided task to use the full project:
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:
centaur task --no-redact "Fix issue #42"Choose a direct export mode:
centaur --export --mode changedcentaur --export --mode stagedcentaur --export --mode compactAdd an explicit task to a direct export:
centaur --export --task "Fix issue #42"The same one-run override works for direct exports:
centaur --export --no-redactfull 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.
Export data
Section titled “Export data”Copy explicitly selected datasets in their native format and prepare an analysis prompt:
centaur data data/games.csv data/quotes.jsonl --task "Check missing timestamps and joins"centaur data "data/player stats.parquet" --no-clipboardcentaur data data/events.json --redactThe 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.
Profile a live database
Section titled “Profile a live database”Set DATABASE_URL for Postgres or Supabase, or MONGODB_URI for Mongo, then run:
centaur db profile --engine postgres --redactcentaur db profile --engine mongo --sample 500 --format json --redactChoose 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.
Apply and recover
Section titled “Apply and recover”Read a complete patch response from the clipboard, a UTF-8 file, or standard input:
centaur --clipboardcentaur --file response.txtcentaur --stdin < response.txtThe expected block format is:
File: src/example.rs<<<<<<< SEARCHfn old() {}=======fn new() {}>>>>>>> REPLACETo create a file, leave SEARCH empty:
File: src/new_file.rs<<<<<<< SEARCH=======fn brand_new() {}>>>>>>> REPLACETo 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:
centaur --dry-run --clipboardNon-interactive use
Section titled “Non-interactive use”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:
generate-centaur-patch | centaur --stdin --dry-rungenerate-centaur-patch | centaur --stdin --yesThe optional local Ollama fallback can repair unmatched blocks, but its output still passes through the deterministic planner and one transactional write:
centaur --llm auto --clipboard --yesRevert changes
Section titled “Revert changes”Revert the latest session in this workspace, or name an older session:
centaur undocentaur undo <session-id>List sessions for this workspace:
centaur historyIntegrations
Section titled “Integrations”Set up the current project for Codex and Claude Code and add .centaur/ to .gitignore:
centaur initcentaur init --forceConfigure supported MCP clients and their commands or skills:
centaur install --client codexcentaur install --client claude-codeConfigure one MCP client or run the workspace-scoped stdio server:
centaur mcp installcentaur mcp serve --workspace <path>Install a Centaur command or skill:
centaur skill installConnecting web clients without copying
Section titled “Connecting web clients without copying”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:
centaur mcp serve --workspace <path>Isolated worktrees
Section titled “Isolated worktrees”Create, list, or remove a task worktree:
centaur worktree create <task-id>centaur worktree listcentaur 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.
Configuration
Section titled “Configuration”Create the default configuration or print its location:
centaur config initcentaur config pathcentaur config redactioncentaur config redaction offcentaur config historycentaur config history --keep 25centaur config destination claude --context-tokens 80000Defaults:
[export]redact_by_default = truecopy_prompt = trueopen_export_directory = trueprompt_mode = "first"max_attachments_per_message = 20max_attachment_chars = 5000000context_token_budget = 200000default_scope = "auto"
[chat]default_target = "auto"default_browser = "default"
[history]completed_handoff_limit = 50
[research]summary_chars = 800instructions = ""return_format = "compact"
[companion]send_mode = "review"show_progress = truenotifications = truealways_on_top = falseredact_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:
[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:
[export.context_token_budgets]claude = 80000team-chat = 32000Run 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.
Prompt templates
Section titled “Prompt templates”Manage workflow prompt templates:
centaur prompt showcentaur prompt copycentaur prompt edit --singlecentaur prompt editcentaur prompt resetCustom 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.
Updating
Section titled “Updating”Reinstall the latest public release:
centaur updateThe 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.