Files
luxe/docs/guide/cli.md
Evan Whittaker bf86df5098 luxe update and /update, editable question answers, and a version bump owed once per release
- luxe update and /update update Luxe with the command for however it was installed (cargo or
  Homebrew), run one program at a time with the terminal attached, then check that the luxe on
  PATH is the new version. Luxe never downloads or replaces its own binary. The start screen says
  "Update available · /update".
- A question's typed answer edits at its caret: arrows, word jumps, Home, End and Delete work,
  and up and down move through a wrapped answer before leaving it.
- The version check owes a bump once per release: the version on main is the next release, and
  only a released one (a v-tag) has to move.
- Dependency updates arrive through the sync, so Dependabot and the weekly jobs no longer run here.
2026-10-17 14:14:27 -05:00

5.9 KiB

title, summary, order, group
title summary order group
Command line Every luxe command and flag. 2 Reference

luxe with no command opens the interface. luxe --help, and --help after any command, prints the same reference. luxe --version prints the version.

Starting a session

Flag Does
-c, --continue Resume the most recent session in this project
--resume <id> Resume a session by ID; see luxe sessions list
--from-pr <number> Resume the session that worked on a pull request
--issue <number> Start on a GitHub issue, in a worktree of its own
--pr <number> Check out a pull request in a worktree and start a session there
--worktree [<branch>] Work in a worktree of its own, on a new or named branch
--plan Start in plan mode: read, ask, and write only the plan

See Git and GitHub and Sessions and context.

Model

Flag Does
--model <id> The model, as an ID or provider/id, which also picks the provider
--provider <id> The provider
--thinking <level> off, minimal, low, medium, high, xhigh or ultra. An unknown level is ignored with a warning.
--api-key <key> The key, or $VAR, or !command. A key typed here is visible to other users of the machine, so prefer the other two.
--base-url <url> The endpoint, including its version, such as /v1

These win over the environment and your config for this run only. See Models and providers.

Permissions and tools

Flag Does
--permission-mode <mode> default, strict, read-only or yolo
--read-only The same as --permission-mode read-only
--yolo Allow everything, with the guardrails off
--auto-approve Start with every prompt approved. Interface and --rpc only.
--on-ask <allow|deny> What a prompt becomes with nobody to answer: allow by default. Headless and loop only.
--trust-project Let a project's hooks, permission rules and servers apply
--no-tool <name> Turn a tool off for this run
--with-tool <name> Turn on a tool your config turned off

An unknown --permission-mode stops the run with an error. It never falls back to a more permissive mode.

See Security and permissions and Tools.

Without the interface

Flag Does
--headless Run one prompt and exit
-p, --prompt <text> The prompt, for --headless
--format <text|json> text streams the reply to stdout and tool activity to stderr. json writes one event per line, with token usage.
--rpc Speak the RPC protocol on stdin and stdout
--github-writes Let an --rpc client publish to GitHub: comments, reviews, thread answers, and opening, merging or restacking pull requests. Refused under --read-only.
luxe --headless -p "list the TODO comments in src/" --format text

A headless run needs -p and a model: --model, LUXE_MODEL, your last choice or default_model in models.json. It refuses to start without either. It exits with status 1 when the turn fails or Luxe stops before the turn ends, so a script can tell a failure from an answer without reading the output.

Commands

Command Does
luxe auth login [provider] Sign in. --method api-key or subscription when a provider has both, --stdin to read a key from a pipe, --api-key <key> to store one given here, --no-verify to skip checking it.
luxe auth list Every provider and how it is configured
luxe auth status [provider] A credential's type, where it came from, and when it expires
luxe auth logout <provider> Remove a stored credential
luxe models list Models you can use. --provider <id> filters, --configured lists only the models models.json or auth.json names.
luxe models show <provider/id> What Luxe knows about a model, and where each value came from. A bare ID uses the active provider.
luxe models refresh Refresh the model catalog. --force even if it is fresh.
luxe sessions list Sessions in this project, newest first
luxe mcp list Configured MCP servers
luxe mcp add --id <id> --name <name> Add a server to the project's .luxe/mcp.json, with --command "<program> <args>" or --url <url>. It counts as a project's server.
luxe mcp remove --id <id> Remove a server from the project's .luxe/mcp.json
luxe mcp tools Every server's tools
luxe mcp login --id <id> Sign in to a server, in a browser
luxe loop start Start or continue an autonomous run. --max-turns, --compact-percent, --pause-percent, --quiet.
luxe loop status The run's iteration, phase and cost
luxe loop pause, luxe loop resume, luxe loop stop Pause, clear a pause, or stop the run
luxe loop phase The current phase. --set <n> changes it.
luxe loop fresh Reset the run's turn count; see Autonomous runs
luxe docs [page] Read this guide, offline and for the installed version. --search <words> finds lines across every page.
luxe doctor Check which tools, language servers and debug adapters work
luxe update Update Luxe with the command for however it was installed; see Updates. --check only reports.
luxe init Set up a theme, a provider, the tools and the start screen, and write them to ~/.config/luxe/config.json. --defaults skips the questions, --force starts from an empty file; see Editing.
luxe wire <log> Summarize a LUXE_WIRE_LOG capture; see Troubleshooting. --tools breaks the tool schemas' size down per tool.

Every command also takes the model and permission flags above.