Files
luxe/docs/guide/cli.md
Evan Whittaker a0666d6c81 luxe 0.1.4: remembered models, wheel-driven lists, and a steadier phone app
- luxe starts on the model you last chose in this project, then the last one anywhere. Signing in
  opens the model picker instead of choosing for you.
- Every list in a modal takes the mouse wheel and a draggable scrollbar.
- The phone app shows reasoning in full, stays put while you read back through a long session, and
  shows a question's answer on its card.
- On Windows, luxe update replaces the running luxe, and a signed-in install no longer sees setup
  again.
- The file tree no longer shows "engine busy" in a large project, loop output is easier to follow,
  and the name is written lowercase.

The CHANGELOG has the full list.
2026-10-20 13:51:34 -05:00

7.2 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 join [id] Join a session another luxe is running, speaking the RPC protocol on stdin and stdout. The id can be its start, or the luxe's process id; without one, it joins the session running in this folder.
luxe join --list Sessions running on this machine that can be joined
luxe remote Serve this machine's sessions to your own phone or tablet. Listens on this machine only, for Tailscale Serve to carry to your devices, and lets in this machine's tailnet owner from a paired device.
luxe remote --port <n> The port it listens on (default 4519)
luxe remote --allow <login> Also let this tailnet login in, as Tailscale names it (alex@github). Repeatable.
luxe remote setup Check Tailscale, offer to publish the bridge on your tailnet with Tailscale Serve, offer to run it at login as a user service, then show a QR code to pair a device. Each step that changes something outside luxe asks first.
luxe remote pair Show a QR code and link that pair one phone or tablet. They work once, within ten minutes.
luxe remote devices The paired devices
luxe remote devices revoke <id> Unpair a device. Its open sessions close within a few seconds.
luxe remote service remove Stop the bridge's user service and stop it starting at login
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.