Command line
Every luxe command and flag.
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 textA 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 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.