# Complete Guide to Worktrunk Subcommands: CLI Reference > Explore all seven Worktrunk subcommands switch list remove merge step hook and config to efficiently manage Git worktrees automate workflows and configure the CLI tool. - Repository: [Maximilian Roos/worktrunk](https://github.com/max-sixty/worktrunk) - Tags: api-reference - Published: 2026-09-14 --- **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`](https://github.com/max-sixty/worktrunk/blob/main/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`](https://github.com/max-sixty/worktrunk/blob/main/src/cli/mod.rs), with implementation logic distributed across `src/commands//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. ```bash 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`](https://github.com/max-sixty/worktrunk/blob/main/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. ```bash 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`](https://github.com/max-sixty/worktrunk/blob/main/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. ```bash 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`](https://github.com/max-sixty/worktrunk/blob/main/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. ```bash 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`](https://github.com/max-sixty/worktrunk/blob/main/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. ```bash 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. ```bash 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`](https://github.com/max-sixty/worktrunk/blob/main/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). ```bash 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 `** — Change working directory before execution - **`--config `** — 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`](https://github.com/max-sixty/worktrunk/blob/main/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 ` 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`](https://github.com/max-sixty/worktrunk/blob/main/.worktrunk.toml) within the repository root. Use `wt config edit` to modify these files directly in your default editor.