CLI Reference

Ante can run as an interactive TUI, a one-shot headless command, a long-lived protocol server, or a channel gateway.

ante [OPTIONS] [COMMAND]

Commands

Command	Description
ante	Start the interactive TUI. If -p / --prompt is provided, run in headless mode instead.
ante auth	Sign in, store API keys, and manage stored credentials without starting a session.
ante usage	Report Claude Code and Codex subscription quotas without starting a session.
ante serve	Run a long-lived protocol server over stdio, a Unix socket, or WebSocket.
ante gateway	Run the Slack / Discord channel gateway.
ante update	Check for the latest Ante release and install it if available.
ante offline	Manage the local inference engine used by offline mode.
ante rage	Collect a redacted bug-report bundle (logs + environment) to share with the Ante team.
ante catalog	Print the loaded provider catalog as JSON.
ante doctor	Run a boot-time self-check and report startup phase timings.
ante <name>	Run an external ante-<name> application.

Global option

--profile <NAME> selects an existing ~/.ante/<name>.settings.json as the settings file for the whole process, reads and writes alike. It can appear before or after any subcommand, and ANTE_PROFILE is equivalent. An unknown profile warns and falls back to ~/.ante/settings.json rather than creating a new file. The bundled bare profile is seeded as a real file on first use and disables skills, MCP servers, session saving, auto-memory, and ambient UI features.

ante --profile work
ante update --profile work
ANTE_PROFILE=work ante doctor

ante

ante [OPTIONS]

Without --prompt, Ante starts the interactive TUI. With --prompt, Ante runs one headless task and exits.

The TUI needs stdout attached to a terminal. Redirecting or piping it (ante > log.txt) is refused up front with a message pointing at headless mode, rather than failing later on a cursor-position query.

Flag	Description
-m, --model <MODEL>	Override the default model name.
--provider <PROVIDER>	Override the API provider by catalog provider name.
--effort <LEVEL>	Override the model's effort level for this run: min, low, medium, high, xhigh, or max.
--yolo	Skip tool approval prompts for the session.
--fullscreen	Start the TUI chat on the alternate screen with Ante-managed scrollback for this run. Does not persist the render_mode setting and is ignored in headless mode.
--permission-mode <MODE>	Override the permission mode for this run: strict, auto, or yolo. Conflicts with --yolo. Headless runs honor the override and deny calls that would require an interactive approval.
--system-prompt <PROMPT>	Replace the default system prompt entirely. Conflicts with --system-prompt-file. Persist a default with the system_prompt setting.
--system-prompt-file <PATH>	Read the replacement system prompt from a UTF-8 file. Conflicts with --system-prompt.
--append-system-prompt <TEXT>	Append content to the default system prompt. Persist a default with the append_system_prompt setting.
--short-prompt	Use shorter built-in tool descriptions for this run; the system instructions are already compact and stay the same. Persist the default with the short_prompt setting.
--skills	Load skills for this run, overriding the skills setting. Conflicts with --no-skills.
--no-skills	Skip skill discovery for this run, overriding the skills setting. No skills are advertised to the model or available as slash commands.
--include-skills <SKILLS>	Add exact skill names to this session, replacing the include_skills setting. Pass a comma-separated value or repeat the flag. Does not re-enable skills when --no-skills or "skills": false is active.
--exclude-skills <SKILLS>	Remove exact skill names from this session, replacing the exclude_skills setting. Pass a comma-separated value or repeat the flag; exclusions win over inclusions.
--enable-auto-memory	Enable auto-memory for this run, overriding the auto_memory setting. Conflicts with --disable-auto-memory.
--disable-auto-memory	Disable auto-memory for this run, overriding the auto_memory setting. Conflicts with --enable-auto-memory.
--tools <TOOLS>	Replace the default tool set with exactly these tools. Pass a comma-separated value or repeat the flag; a space-separated list is rejected. Overrides the tools setting. The old --allowed-tools name has been removed.
--include-tools <TOOLS>	Add tools on top of the default set, or on top of the --tools base set. Pass a comma-separated value or repeat the flag.
--exclude-tools <TOOLS>	Remove tools after --tools and --include-tools are applied. Pass a comma-separated value or repeat the flag. The deprecated --disallowed-tools alias remains accepted.
--output-format <FORMAT>	Headless output format: json, human, or minimal. Defaults to minimal.
-p, --prompt <PROMPT>	Prompt to run in headless mode. Also supports stdin when piped.
--draft <TEXT>	Start the interactive TUI with editable text in the composer, without sending it. Works with --resume <SESSION_ID>; conflicts with -p / --prompt.
--check	Run a verification pass after the headless task completes.
-r, --resume [SESSION_ID]	Resume by ID, or omit the ID to open the interactive session picker for the current directory. Headless runs require an ID.
--session-save	Save the session transcript and resumable snapshot, overriding the session_save setting. Conflicts with --no-session-save.
--no-session-save	Do not save the session transcript or resumable snapshot, overriding the session_save setting. Conflicts with --resume.
--offline-model [MODEL]	Start local inference for a TUI or headless run. Accepts a GGUF path, discovered filename, or verified model name/URL; omit the value to start the default saved with ante offline use. Conflicts with --model and --provider.
-h, --help	Print command help.
-V, --version	Print the Ante version.

The session flags in this table configure the default TUI/headless run. Supplying one alongside a subcommand is an error rather than a silently ignored option; the process-wide --profile flag above is the exception.

Examples

ante
ante -p "explain what this project does"
git diff | ante -p "review this diff for bugs"
ante --provider openai --model gpt-6.1-sol -p "refactor the database module"
ante --effort max -p "find the race condition in the scheduler"
ante --draft "Review the authentication changes"
ante --profile work
ante --profile bare -p "review this repository"
ante --resume ses_01ARZ3NDEKTSV4RRFFQ69G5FAV -p "now add tests"
ante -p "summarize this repo" --enable-auto-memory

When resuming, the saved system prompts and prompt mode take precedence over --system-prompt, --system-prompt-file, --append-system-prompt, and --short-prompt. These flags apply to fresh sessions from this launch, including a later /clear.

Since v0.3.1, --resume also honors --tools, --include-tools, and --exclude-tools. Without --tools, the base set comes from the current tools setting or the default tool set; it is not restored from the saved conversation. See resuming a headless session for examples.

ante auth

ante auth list [--json]
ante auth login <NAME> [--no-browser]
ante auth logout <NAME>
ante auth add <NAME>
ante auth rm <REFERENCE>

Manage the credentials Ante stores, without starting a session. A NAME is a provider, OAuth profile, or MCP server name, optionally with a /label for a second account (anthropic/work).

Command	Description
list	Show stored credentials: kind, issuer, account, state (set, valid, expired, invalid, unreadable), and the providers that use each one.
login <NAME>	Sign in through the browser. NAME is an OAuth profile (anthropic, openai, antix, or one of your oauth_profiles), a provider that signs in with one (anthropic-subscription), or a remote MCP server. Running it again signs in again.
logout <NAME>	Forget a sign-in.
add <NAME>	Store an API key, read from stdin (prompted on a terminal). When NAME is a provider, Ante checks the key against it first and refuses one the provider rejects.
rm <REFERENCE>	Forget a stored credential: a key (NAME or secret:NAME), a sign-in (oauth:NAME), or a helper's saved output (helper:NAME, so the helper runs again now).

Flag	Description
--json	list only: print one JSON object containing a credentials array, with no secret values. Available since v0.3.1.
--no-browser	login only: print the authorization URL instead of opening a browser, for remote machines.
-h, --help	Print command help.

Examples

ante auth login antix
ante auth login anthropic/work --no-browser
ante auth login linear                       # an MCP server in mcp_servers
echo "$TOGETHER_API_KEY" | ante auth add together
ante auth rm oauth:anthropic/work
ante auth list

Credentials are stored as owner-only files under ~/.ante/auth/. See Credentials for how providers refer to them.

JSON credential inventory

ante auth list --json returns {"credentials": [...]}. Each entry contains reference, kind (secret, oauth, or helper), name, issuer, account, state, and used_by (provider IDs). issuer and account can be null; an empty store returns {"credentials": []}. Environment variables are not stored credentials and are not listed.

ante auth list --json | jq '.credentials[] | {reference, state, used_by}'

The reference is the exact string a protocol client can send as credential in StartSession or ResumeSession to choose an account before its first request. Send the reference, never the key or token itself.

ante usage

ante usage [NAME] [--json]

Available since v0.3.2. Reports subscription quota percentages and reset times for stored Claude Code (anthropic) and Codex (openai) OAuth accounts. Without NAME, it checks every supported stored sign-in, including labeled accounts. It reports provider subscription limits; session token totals remain in the TUI's /usage dialog, and API-key billing is not included.

NAME is an exact stored sign-in name such as openai/work, without the oauth: prefix. An unknown or unsupported name fails instead of selecting another account. Use ante auth list to find stored names.

ante usage
ante usage anthropic
ante usage openai/work --json

--json prints one object with a subscriptions array. Each account has credential (the stored name), provider (the stable OAuth profile ID, anthropic or openai), email, plan, and status. email and plan may be null.

• ready includes windows, each with label, used_percent, and resets_at (a UTC timestamp or null). An empty window list means the provider reported no limits.
• expired indicates that the sign-in must be renewed with ante auth login <NAME>.
• unavailable includes a reason describing why the quota could not be read.

The command prints the full report before exiting with status 1 if any selected account is expired or unavailable. With no supported stored sign-ins, it succeeds with {"subscriptions": []} in JSON mode or a sign-in hint in text mode; scripts that require an account should also check for an empty list.

ante serve

ante serve [OPTIONS]

Server mode exposes the Ante protocol over stdin/stdout by default, over a Unix domain socket when --sock is provided, or over WebSocket when --ws is provided.

Flag	Description
--stdio	Serve the JSONL protocol over stdin/stdout. This is the default transport. The three transport flags are mutually exclusive.
--sock [PATH]	Serve the protocol over a Unix domain socket. Defaults to run/serve.sock in the Ante home when no path is given.
--ws <ADDR>	Serve the protocol over WebSocket on the given loopback socket address.
--offline-model [MODEL]	Load a local or verified model at startup; accepts the same model references as a normal run. Omit the value to load the saved default.
-h, --help	Print command help.

note

serve is session-agnostic, so it does not accept the session flags (--model, --provider, --yolo, --system-prompt, --tools, …). The connecting client configures those per session over the protocol.

The global --profile flag remains accepted and selects the settings file used by the server process.

caution

--ws requires a nonempty ANTE_SERVE_TOKEN and accepts loopback addresses only (127.0.0.0/8, ::1). Clients must send Authorization: Bearer <token> in the WebSocket upgrade request; a missing or wrong token returns HTTP 401, and handshakes time out after 10 seconds. A non-loopback address such as 0.0.0.0:8080 is refused before the listener binds. To reach the daemon from elsewhere, use an SSH tunnel or an authenticating reverse proxy with TLS (wss://).

note

One host owns a socket at a time. --sock takes an exclusive lock on a .lock file beside the socket, so a second ante serve --sock on the same path refuses to start and leaves the running host's socket untouched. A socket file left behind by a crashed host holds no lock and is replaced on the next start.

Each client connection drives its own session. A client's Shutdown ends only that connection — the host keeps listening, and exits on SIGINT or SIGTERM.

Examples

ante serve
ante serve --sock                        # ~/.ante/run/serve.sock
ante serve --sock /tmp/ante.sock
ANTE_SERVE_TOKEN="your-secret-token" ante serve --ws 127.0.0.1:8080

ante gateway

ante gateway [OPTIONS]

Since v0.2.2, this command dispatches to the separately installed ante-gateway application and passes the remaining arguments through unchanged. The gateway connects to an Ante host via the SDK and uses its channels config for Slack and Discord. See Gateway mode for installation; a missing executable exits with status 127.

Flag	Default	Description
--config <PATH>	~/.ante/channels.json	Path to the channels configuration file.
--connect <ENDPOINT>	unix:~/.ante/run/serve.sock	Ante host endpoint: unix:<path>, ws://<addr>, wss://<addr>, or stdio. Start a host with ante serve --sock.
--model <MODEL>	—	Model to request (otherwise uses host settings).
--provider <PROVIDER>	—	Provider to request (otherwise resolved by host).
--output-format <FORMAT>	minimal	Gateway stdout format: json, human, or minimal.
-h, --help	-	Print command help.

Examples

ante gateway
ante gateway --connect unix:/tmp/ante.sock
ante gateway --provider anthropic --model claude-sonnet-5-5
ante gateway --config ./channels.json --output-format human

ante update

ante update [OPTIONS] [CHANNEL]

The update command checks for a newer Ante release and installs it when one is available. Without arguments, it follows the channel in the active settings file (defaults to stable); select a named settings file with the global --profile flag. Passing a channel — either as a positional argument or via --channel — overrides the tracked channel for this run only. See Update & Channels for the full list of channels.

Argument	Description
[CHANNEL]	Release channel to update from (stable or nightly). latest is accepted as a legacy alias for stable. Conflicts with --channel and --version.

Flag	Description
--channel <CHANNEL>	Release channel to update from. Equivalent to the positional form.
--version <VERSION>	Install an exact release instead of the channel's newest release. Accepts values with or without a leading v, such as v0.3.2 or 0.3.2. Conflicts with channel arguments.
-h, --help	Print command help.

Examples

ante update
ante update nightly
ante update --channel stable
ante update --version v0.3.2
ante --profile work update

ante offline

ante offline <COMMAND>

Manage the engine, models, and saved load preferences used by offline mode, without starting a session.

Subcommand	Description
install	Download and install Ante's pinned llama.cpp build. A no-op when already current; replaces a different or unrecorded build.
status [--json]	Report the engine build and path, model directory, default model, managed router, other local servers, and available memory.
list [--json]	List local GGUF and verified models with size, maximum context, estimated memory fit, and a default marker. JSON includes a reference accepted by use and --offline-model.
use <MODEL> [OPTIONS]	Save the default model and any supplied load preferences, without starting the engine or downloading a model. Always prints a Loads with: summary.
stop	Stop this Ante home's managed router, whether kept by an earlier launch or currently in use. This affects every session sharing that router.

MODEL accepts a GGUF path, discovered filename, or verified model name/URL from ante offline list. Bare --offline-model starts the default saved with use; if none is set, it fails with instructions to choose one. Verified models download on first load, not during use.

Load options for use (v0.2.12):

Option	Description
--context <TOKENS>	Context window from 8192 up to the model's maximum.
--thinking on / --thinking off	Enable or disable thinking.
--temperature <T>	Sampling temperature from 0 to 2; pass default to clear the saved override.
--args "<OPTIONS>"	Replace extra llama.cpp options, with shell-style quoting. Pass --args "" to clear them.

Each supplied option replaces only its own saved value; other preferences stay as they are. Context and temperature flags are range-checked before saving. Ante checks extra-argument syntax and rejects reserved or removed options; other errors may only surface when loading a model. These preferences apply to subsequent TUI, headless, and serve loads; see Model preferences.

Examples

ante offline install
ante offline status
ante offline list --json
ante offline use Qwen3.5-9B --context 32768 --thinking off --temperature 0.7
ante --offline-model
ante --offline-model -p "Explain this code"
ante serve --sock --offline-model

ante rage

ante rage [OPTIONS]

When something goes wrong, ante rage gathers the context the Ante team needs to investigate into a single shareable archive that you can attach to a GitHub issue. By default it writes ./ante-rage-<timestamp>.tar.gz and prints a short summary. Nothing is uploaded — the bundle stays local until you share it.

With --no-compress, the finished report is a directory at ./ante-rage-<timestamp> or the exact --output path. Both formats refuse to overwrite existing output, and the parent directory must already exist. If compression fails, Ante writes a report directory at the archive path with .uncompressed appended.

Secrets are redacted before anything is written. API keys and OAuth tokens are reported only as present/absent (never their values), credentials embedded in URLs and known token shapes are masked, conversation transcripts and system prompts are excluded, and ~/.ante/auth/*.json and channels.json are never included.

The archive contains:

File	Contents
report.md	Ante version, OS/architecture, shell, git branch, the resolved model/provider, a provider authentication table (present/absent), the telemetry installation id if one exists, and a redaction notice.
env.txt	Ante-relevant environment variables. Safe values are shown verbatim; known secrets appear as <SET> / <UNSET> only.
settings.redacted.json	~/.ante/settings.json with secrets removed (MCP server credentials and custom system_prompt / append_system_prompt text are stripped).
catalog.redacted.json	~/.ante/catalog.json with secrets removed, included only when a custom catalog exists.
logs/	Recent application and crash logs, filtered and scrubbed; each copy is prefixed with its date (<date>-<name>). DEBUG/TRACE lines are dropped so request bodies never enter the bundle.

When a project settings file applies to the directory you collect from, its .ante/settings.json is included too, redacted the same way as the user file — so the bundle shows the settings that were actually in effect.

By default the newest logs are collected, up to 10 files or 10 MB (crash logs are always prioritized). Use --since to collect everything within a time window instead.

Flag	Description
--output <PATH>	Exact output path: an archive normally, or a report directory with --no-compress. Defaults to ./ante-rage-<timestamp>.tar.gz or ./ante-rage-<timestamp>, respectively.
--no-compress	Write the finished report as a directory instead of a .tar.gz.
--verbose-logs	Also include DEBUG/TRACE log lines. Conversation transcripts and system prompts are still excluded.
--since <DURATION>	Collect every log modified within the window, ignoring the file-count and size limits. Accepts <n>d, <n>h, <n>m, or a bare number of days (for example 7d, 48h, 90m, 2).
-h, --help	Print command help.

Examples

ante rage
ante rage --output ./ante-bug.tar.gz
ante rage --since 7d
ante rage --no-compress

ante catalog

ante catalog

Print the merged provider catalog (built-in presets plus ~/.ante/catalog.json) to stdout as a JSON document with a single providers array, in catalog order. Each provider embeds its preferred models with user model overrides applied, so the output is a published view for consumers; it is not the config-file schema and does not round-trip into ~/.ante/catalog.json. Warnings for skipped catalog entries go to stderr, so stdout stays a clean JSON document that pipes into jq. See the Catalog Reference for the config-file schema.

Examples

ante catalog
ante catalog | jq '.providers[].id'

ante doctor

ante doctor

Boot the same runtime a real launch uses — load the merged catalog, start a daemon session, and render the first TUI frame — then print a readiness report with per-phase timings. Use it to confirm Ante is installed and configured correctly, or as a CI smoke test ("does Ante boot, does the first frame render").

It needs no TTY and no API key: MCP warm-up is skipped and the session reaches readiness from the catalog alone. The report lists five checks — home (the Ante home and input history are writable), project (the project settings file that applies to this directory, or that none was found), catalog (provider/model counts), session (the resolved provider/model), and first frame (the headless render) — followed by a total. Warnings (such as no authenticated provider, a skipped catalog entry, a settings.json parse notice, or a key dropped from a project settings file) are listed below the table. doctor exits non-zero if any hard check fails, including an unwritable Ante home, so it works in scripts.

Examples

ante doctor
ante doctor || echo "ante is not healthy"

External applications

An unrecognized command name dispatches to an executable named ante-<name>, following the same convention as git subcommands:

# Runs ~/.ante/bin/ante-deploy or ante-deploy from PATH
ante deploy --target production

Ante searches ~/.ante/bin before PATH, falls back to ~/.cargo/bin if missing from PATH, passes remaining arguments through unchanged, and mirrors the application's exit status. Built-in subcommands always win, so an external executable cannot shadow ante update or another built-in. If no executable is found, Ante reports exit status 127 and still suggests a similarly named built-in for likely typos.

External applications receive ANTE (the absolute path to the Ante binary), ANTE_APP (the resolved app name), and the selected ANTE_PROFILE when one is active. Like help and usage errors, dispatch occurs before Ante starts its runtime, logging, telemetry, or crash hook.

Output Formats

Format	Description
minimal	Print agent messages, info, and errors only.
human	Print all events in a human-readable format.
json	Print events as JSON lines for machine processing.

Related Pages

• TUI Mode
• Headless Mode
• Server Mode
• Gateway Mode
• Tools Reference