Complete Guide to Worktrunk Subcommands: CLI Reference

Worktrunk provides seven primary subcommands—switch, list, remove, merge, step, hook, and config—that enable developers to manage Git worktrees, automate workflows through hooks, and configure the tool via a unified wt CLI.

Worktrunk is an open-source Git worktree manager written in Rust that streamlines parallel development workflows. The command-line interface is built with clap and defined centrally in src/cli/mod.rs, where each top-level subcommand delegates to dedicated modules implementing the actual behavior. This article documents every available subcommand, its specific purpose, and practical usage examples drawn directly from the source code.

Worktrunk CLI Architecture

The wt binary organizes functionality into a declarative command hierarchy. All subcommand definitions reside in src/cli/mod.rs, with implementation logic distributed across src/commands/<subcommand>/mod.rs. Global options—such as -C for changing the working directory, --config for specifying custom configuration files, and -y to skip approval prompts—are available across all commands.

Core Worktrunk Subcommands

switch

The switch subcommand changes to an existing worktree or creates a new one, serving as the primary navigation tool for parallel development contexts. It supports intelligent shortcuts including ^ (parent branch), @ (default branch), - (previous worktree), and PR/MR references (pr:{N}, mr:{N}).

Key flags include --create to initialize new branches, --base to specify an upstream reference, --clobber to force overwrite existing directories, and -x to execute a program after switching.

wt switch feature-auth          # Switch to existing worktree

wt switch -                     # Toggle to previous worktree (like cd -)

wt switch --create new-feature  # Create branch and worktree simultaneously

wt switch pr:42                 # Switch to worktree for pull request #42

list

The list subcommand displays all worktrees and their current status, supporting both interactive table views and machine-readable output formats. In src/commands/list/mod.rs, the implementation handles progressive rendering for large repositories and optional CI status integration.

Available flags include --full for CI status and LLM-generated summaries, --branches to include branches without worktrees, --remotes for remote tracking information, and --format=json for programmatic consumption.

wt list --full                  # Table with CI status and AI summaries

wt list --format=json           # Machine-readable JSON output

wt list --branches --full       # Include branches lacking worktrees

remove

The remove subcommand safely deletes worktrees and optionally their associated branches. The implementation in src/commands/remove/mod.rs provides safety mechanisms to prevent accidental data loss.

Safety flags include --force to bypass confirmation prompts, --reap to remove untracked branches, and --no-delete-branch to preserve the Git branch while removing only the worktree directory. The --foreground flag ensures the operation completes before returning control.

wt remove feature-auth          # Remove worktree, keep branch

wt remove --force feature-auth  # Force removal without prompts

wt remove --reap                # Clean up untracked branches

merge

The merge subcommand integrates upstream changes into the current worktree, defaulting to the repository's default branch as the merge source. The logic in src/commands/merge/mod.rs supports multiple merge strategies and cleanup operations.

Strategy flags include --squash/--no-squash for commit consolidation, --rebase/--no-rebase for linear history maintenance, and --ff/--no-ff for fast-forward control. The --remove flag performs post-merge worktree cleanup automatically.

wt merge                        # Merge default branch into current worktree

wt merge --no-ff               # Force merge commit even if fast-forward possible

wt merge --remove               # Delete worktree after successful merge

step

The step subcommand provides a namespace for atomic workflow operations that execute single Git actions with full hook integration. Implemented in src/commands/step/mod.rs, it supports commit, squash, rebase, and cherry-pick operations.

Each step runs the corresponding Git command and triggers the appropriate pre- and post-operation hooks defined in the Worktrunk configuration. This ensures consistent automation across different Git operations.

wt step commit -m "Update auth" # Commit with hook execution

wt step squash                  # Squash commits interactively

wt step rebase main             # Rebase onto main with hook support

hook

The hook subcommand manually executes Worktrunk hooks for the current worktree context. Hook types are validated against the HOOK_TYPE_NAMES constant and include lifecycle events like pre-merge and post-switch.

Use wt hook --list to enumerate available hook types configured in the repository.

wt hook pre-merge               # Execute pre-merge hooks manually

wt hook post-switch             # Run post-switch hooks

wt hook --list                  # Display available hook types

config

The config subcommand manages Worktrunk's TOML configuration at both user and project levels. Defined in src/commands/config/mod.rs, it supports extensive nested subcommands for fine-grained control.

Available config namespaces include approvals (approval workflows), cache (caching behavior), ci-status (CI integration), shell (shell completion), state (branch markers and metadata), and vars (environment variables).

wt config edit                  # Open configuration in $EDITOR

wt config state marker set 🚀   # Tag current branch with emoji marker

wt config vars set API_KEY     # Configure environment variables

Global CLI Options

All Worktrunk subcommands inherit common flags defined in the root command structure:

• -C <PATH> — Change working directory before execution
• --config <FILE> — Specify custom configuration file path
• -v, --verbose — Increase output verbosity
• -y, --yes — Automatically confirm prompts without interaction

Summary

• switch: Navigate between worktrees using shortcuts (-, @, pr:N) or create new ones with --create
• list: Visualize worktree states with optional CI data via --full or JSON output via --format=json
• remove: Safely delete worktrees with branch cleanup options (--reap, --no-delete-branch)
• merge: Integrate upstream changes with strategy controls (--squash, --rebase, --ff)
• step: Execute atomic Git operations (commit, squash, rebase) with hook integration
• hook: Manually trigger lifecycle hooks (pre-merge, post-switch) or list available types
• config: Manage TOML settings including markers, variables, and CI integrations through subcommands

Frequently Asked Questions

What is the difference between wt switch and wt step?

wt switch manages worktree navigation and creation, handling the filesystem directories and branch checkouts, while wt step executes Git operations within the current worktree context. Switch changes where you work; step changes what you commit.

How do I list all available hooks in Worktrunk?

Execute wt hook --list to display all hook types defined in the HOOK_TYPE_NAMES constant from src/commands/hook/mod.rs. Common types include pre-merge, post-switch, pre-remove, and post-create.

Can I remove a worktree without deleting its Git branch?

Yes. Use wt remove <branch-name> without additional flags to remove only the worktree directory while preserving the branch. Add the --no-delete-branch flag explicitly to ensure this behavior, or use --force-delete to remove both the worktree and the branch even if it contains unmerged commits.

Where does Worktrunk store its configuration?

Worktrunk uses TOML configuration files managed through the wt config command. User-level settings typically reside in $HOME/.config/worktrunk/config.toml, while project-level settings can be stored in .worktrunk.toml within the repository root. Use wt config edit to modify these files directly in your default editor.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}