Skip to content

CLI Usage

The CLI supports both human-first worktree lifecycle commands and machine-first read commands without launching the full TUI.

Quick command cookbook: lazyworktree list, lazyworktree create ..., lazyworktree delete ..., lazyworktree cleanup, and lazyworktree exec ....

For coding agents and scripts, start with:

lazyworktree describe
lazyworktree doctor --json
lazyworktree worktrees list --json
lazyworktree worktrees resolve --name my-feature --json
lazyworktree notes get my-feature --json

Config Overrides

lazyworktree --worktree-dir ~/worktrees

# Override config values from CLI
lazyworktree --config lw.theme=nord --config lw.sort_mode=active

Listing Worktrees

lazyworktree list              # Table output (default)
lazyworktree list --pristine   # Paths only (scripting)
lazyworktree list --json       # JSON output
lazyworktree ls                # Alias

--pristine and --json are mutually exclusive.

Machine-readable discovery

lazyworktree doctor --json
lazyworktree worktrees list --json
lazyworktree worktrees resolve --name my-feature --json
lazyworktree worktrees get my-feature --json
lazyworktree worktrees context my-feature --json
lazyworktree notes get my-feature --json

These commands are designed for automation:

  • doctor reports repository and tool health without failing when setup is incomplete
  • worktrees resolve turns a name, branch, or path into a canonical worktree path
  • worktrees get reads one exact worktree
  • worktrees context returns note and agent-session context for one worktree
  • notes get returns note metadata in a stable JSON shape

Creating Worktrees

lazyworktree create                          # Auto-generated from current branch
lazyworktree create my-feature               # Explicit name
lazyworktree create my-feature --with-change # With uncommitted changes
lazyworktree create --from-branch main my-feature
lazyworktree create --from-pr 123
lazyworktree create --from-issue 42          # From issue (base: current branch)
lazyworktree create --from-issue 42 --from-branch main  # From issue with explicit base
lazyworktree create -I                       # Interactively select issue (fzf or list)
lazyworktree create -I --from-branch main    # Interactive issue with explicit base
lazyworktree create -P                       # Interactively select PR (fzf or list)
lazyworktree create -P -q "dark"             # Pre-filter interactive PR selection
lazyworktree create -I --query "login"       # Pre-filter interactive issue selection
lazyworktree create --from-pr 123 --no-workspace        # Branch only, no worktree
lazyworktree create --from-issue 42 --no-workspace      # Branch only, no worktree
lazyworktree create -I --no-workspace                    # Interactive issue, branch only
lazyworktree create -P --no-workspace                    # Interactive PR, branch only
lazyworktree create my-feature --exec 'npm test'        # Run command after creation

--exec runs after successful creation. It executes in the new worktree directory, or in the current directory when used with --no-workspace.

Shell mode follows your shell:

  • zsh -ilc
  • bash -ic
  • otherwise -lc

PR creation behaviour:

  • Worktree name always uses the generated worktree name.
  • Local branch name uses the PR branch when you are the PR author.
  • Otherwise it uses the generated name.
  • If requester identity cannot be resolved, it falls back to the PR branch name.

For complete CLI docs, run man lazyworktree or lazyworktree --help.

Deleting Worktrees

lazyworktree delete                # Delete worktree and branch
lazyworktree delete --no-branch    # Delete worktree only

Renaming Worktrees

lazyworktree rename new-feature-name              # rename current worktree (detected from cwd)
lazyworktree rename feature new-feature-name
lazyworktree rename /path/to/worktree new-worktree-name

During rename, the branch is renamed only if the current worktree directory name matches the branch name.

Cleaning Up Worktrees

lazyworktree cleanup              # Choose candidates from a numbered menu
lazyworktree cleanup --all        # Attempt every candidate without prompting
lazyworktree cleanup --all --json # Emit the result as JSON

The interactive menu accepts comma-separated numbers and ranges. Dirty merged worktrees remain visible with a warning but are skipped if selected. --all (also available as --non-interactive) likewise skips registered worktrees with uncommitted changes while continuing with safe candidates and orphaned directories. Merged branches without worktrees are included when prune_stale_branches is enabled. Add --json (which requires --all) to emit aggregate counts and a per-item list including skipped items and their reasons.

Running Commands in Worktrees

Execute a shell command or trigger a custom command key action:

lazyworktree exec --workspace=my-feature "make test"
lazyworktree exec -w my-feature "git status"

# Auto-detect worktree from current directory
cd ~/worktrees/repo/my-feature
lazyworktree exec "npm run build"

lazyworktree exec --key=t --workspace=my-feature  # Launch tmux session
lazyworktree exec --key=_review --workspace=my-feature  # Run palette-only action
lazyworktree exec -k z -w my-feature              # Launch zellij session

# Auto-detect worktree and trigger key action
cd ~/worktrees/repo/my-feature
lazyworktree exec --key=t

exec command behaviour:

  • Uses --workspace (-w) to target a worktree by name or path.
  • Auto-detects worktree from current directory when --workspace is omitted.
  • Accepts either a positional shell command or --key to trigger a custom command.
  • Palette-only custom commands still use their _name identifier with --key.
  • Sets the same managed WORKTREE_*, REPO_*, and contextual LAZYWORKTREE_* environment variables as custom commands in the TUI.
  • Supports shell, tmux, zellij, herdr, and show-output command types.
  • new_tab is ignored for tmux and zellij commands, which have no terminal tab to open. Their configured attach setting decides whether the session opens in the current terminal or is created in the background with instructions for attaching later. new_tab is not supported for Herdr or plain commands in CLI mode.