CLI Commands
Use luvus help <topic> [command] for focused help. Most commands also accept
a trailing --help. Pass-through commands preserve that flag as payload, so
use the explicit luvus help form for them. Help writes to stdout, while
invalid usage writes to stderr.
luvus: Mission control for your AI coding agents
usage: luvus <command> [args]
(no args) launch / attach the TUI --session <name> target one named server session --version, -V print the version --help, -h show compact help help [all|<topic> [command]] show compact, complete, or focused help doctor check optional external tools (git, gh, …) update check for and install a newer Luvus release ping check the server
workspaces: workspace list list workspaces workspace new create a workspace in the current directory workspace open <path> open <path> as a workspace (or focus it if already open) workspace focus <i> focus workspace i (0-based) workspace rename <i> <name> rename workspace i without changing its folder workspace pin <i> pin workspace i (0-based) in the sidebar workspace unpin <i> unpin workspace i (0-based) workspace close [<i>] close a workspace (default: active)
tabs: tab list list tabs in the current workspace tab new new tab tab focus <n> focus tab n (1-based) tab move <from> <to> move a tab to an exact position (1-based) tab move left|right move the active tab one position (--tab N targets one) tab swap <first> <second> exchange two tab positions (1-based) tab rename <name> name a tab (--tab N to target one; empty clears it) tab close [<n>] close a tab (default: active)
panes / agents: pane list list panes and read-only history metrics in the current tab pane split [<id>] [--down] [--no-focus] split a pane (default: side by side) pane focus <id> focus a pane (jumps to its workspace/tab) pane move [<id>] (--tab <n> | --new-tab) move a pane within its workspace pane run [<id>] <cmd...> run a command in a pane pane send [<id>] <text> send raw text to a pane pane read [<id>] print a pane's recent output pane status [<id>] print a pane's agent status and history metrics (any workspace) pane name <name> name a pane so you can mention it (--pane <id>; --clear) pane close [<id>] close a pane agent list list every agent across all workspaces/tabs agent start <name> --kind <k> [--pane <id> | --anchor <id>] [--down] [--timeout <s>] [-- <args>] spawn beside an anchor or reuse a pane, wait until ready, name it agent fork <target> [--name <alias>] [--no-focus] fork a supported agent's session into a sibling pane agent name <name> alias the current agent, same as pane name (--clear to drop) agent send <target> <text> [--wait] [--until STATE] [--timeout <s>] prompt an agent (target = a name, pane id, or kind) agent keys <target> <key>... send control keys (enter, esc, ctrl+c, up, …) agent read <target> [--lines N] [--source visible|recent] print an agent's output agent get <target> one agent's live info (pane, name, kind, status, cwd) agent sessions list resumable sessions found on disk agent resume <id> reopen a resumable session into a pane skill status [<agent>] show enabled state, release, path, and integrity skill enable <agent>|--all opt an agent into the remotely distributed skill skill disable <agent>|--all remove an unmodified managed skill skill update [<agent>] update enabled agents only (all enabled by default) skill show <agent> print an installed agent's SKILL.md <agent> is claude, codex, or opencode wait output <id> --match <text> [--timeout <s>] block until output appears wait agent-status <id> --status done|blocked|working|idle [--timeout <s>] attach <id> open the TUI into a single fullscreen pane
search: search <text...> [--case] find text across every pane's scrollback (docs/63); --case is case-sensitive; returns matches as JSON search --fuzzy <query...> [--scope all|navigate|files|output] [--all-sessions] [--limit <1-200>] [--case] [--json] rank navigation, file paths, and retained output; legacy search stays exact unless --fuzzy is passed
themes: theme list [--json] list built-in, installed, and virtual themes theme path print/create the shared themes directory theme init <id> [--extends <id>] write an editable TOML starter theme validate <path> [--strict] [--json] validate without installing theme install <source> [--yes] install a local file, HTTPS URL, GitHub repo, or community/<id> theme use <id> select and persist a registered theme theme uninstall <id> remove an inactive local theme theme reload rescan installed themes in the selected server
bars: bar list list declared Luvus Bar widgets and live content bar push --id <id> [--region top-right|bottom-right] --content <json> publish validated live widget segments; --content-file, --compact-content, --text and --state supported bar move --id <id> --region top-right|bottom-right|off bar remove --id <id> clear live widget content, preserving placement
appearance: ui sidebar [--side left|right] --width <n> set a sidebar's width (columns) ui sidebar [--side left|right] --hide|--show toggle a sidebar ui dock list list docks and which side each is on ui dock move --id <id> --side left|right place a dock on a side ui dock push --id <id> [--title <t>] [--side left|right] [--rows <json>] feed a module's sidebar dock its rows (JSON array, or piped on stdin). See docs/29 + the website ui notification push --text <text> [--level info|success|warning|error] ui notification clear [--dedupe-key <key>] ui toast <text> flash a one-line message in the UI
modules (extensions): module search [<query>] find modules published to the `luvus-module` GitHub topic module list list installed modules module info <id> show a module's actions / panes / events / source module link <path> register a local module dir (--disabled to skip enabling) module install <owner>/<repo>[/sub] [--ref REF] [--yes] install from GitHub module unlink <id> remove a module from the registry module uninstall <id> unlink + delete a git-installed module's checkout module enable <id> | disable <id> <id> is a module id or the owner/repo it came from module actions list every action across modules module run <id> <action> invoke a module action (captures + logs output) module pane open <id> <entrypoint> [--placement split|overlay|tab] module pane focus <pane> | close <pane> module log [<id>] tail module command logs (--limit N) module config-dir <id> print/create a module's config dir module settings <id> list a module's declared settings and values module settings <id> <key> [<value>] read / write one setting
git: git status branch, ahead/behind, working tree of the current workspace git branches local branches with tracking git log [--limit N] recent commits git open [<workspace>] open the git tab for a workspace files tree print the FILES tree of the active node files open <path> [--target pane|tab|preview] open a file in a view files reveal <path> expand the tree to a path files refresh re-read the tree from disk
diff review: diff list [--layer staged|worktree|untracked|conflict] list exact diff layers diff open [<path>] [--layer <layer>] [--view auto|split|stack] [--placement preview|pane|tab] diff get <path> [--layer <layer>] [--include-patch] inspect a bounded semantic diff diff refresh refresh the shared FILES and DIFF index diff note add --file <path> (--old-line N|--new-line N) --body <text> [--end-line N] [--kind question|issue|suggestion|praise] diff note list [--file <path>] [--state open|resolved|outdated|orphaned] diff note edit <id> --body <text> diff note resolve|reopen <id> diff note remove <id> --yes diff note send --to <agent> [<id>...] [--all-open]
worktrees: worktree list list the current repo's worktrees worktree create <branch> create a worktree + workspace for <branch> worktree open <path> open an existing worktree as a workspace worktree remove <path> remove a worktree (its branch is kept)
orchestration (multiple agents on one project, docs/22): task add "<title>" [--paths <glob>...] [--dep <id>...] [--gate <cmd>] task list list all tasks + their status/assignee task get <id> show one task task claim <id> claim a task for this pane (deps must be done) task next [--start] [--agent <cmd>] claim the next ready task (--start spawns an isolated worker), for an agent loop draining the queue task start <id> [--branch <b>] [--agent <cmd>] spawn an isolated worker: a git worktree + pane, auto-claimed and path-leased task heartbeat <id> --context <0..1> report context usage (blocks done at >85%) task update <id> [--status <s>] [--output <o>] [--note <n>] task done <id> mark done + release its leases task merge <id> integrate the task's branch into luvus/integration (isolated worktree, conflicts block the task) task release <id> return a claimed task to the queue task delete <id> remove a task (release/finish an active one first) lease acquire <glob>... --task <id> reserve file paths (denied if they overlap) lease release <id> release a lease lease list list active path leases
events: events stream live status changes
sessions: session list [--json] list default and named server sessions session attach <name> start or attach the named session session stop <name> [--json] stop only the named session and its panes session delete <name> [--json] delete a stopped named session
remote: --remote <host> [ssh args] attach to a luvus session on <host> over plain ssh
server: server status is the server running, and what version server start start the background server if it isn't up server stop stop the server (and all panes) server restart stop + start (load a newly-installed binary) server update-manifest fetch the latest agent-detection rules from luvus.dev (applies live if the server is up; else on next start) integration install|uninstall <claude|copilot|codex|opencode|kimi|grok> add/remove luvus's session-resume hook (uninstall removes only luvus's hook, never the agent)