CLI reference¶

This page provides a comprehensive reference for all autowt commands, their options, and usage patterns. For a hands-on introduction, check out the Getting Started guide.

autowt <branch-name> / autowt switch¶

(Aliases: autowt switch <branch-name>, autowt sw <branch-name>, autowt checkout <branch-name>, autowt co <branch-name>, autowt goto <branch-name>, autowt go <branch-name>)

Switch to a worktree, or create a new one. Accepts:

• A branch name (e.g., feature-branch)
• A branch name without prefix (if you've configured branch_prefix, you can omit it)
• A path to an existing worktree directory

Intelligently checks out existing branches from your default remote (i.e. origin), or offers to create a new one if none exists.

Interactive Mode: Running autowt switch with no arguments opens an interactive TUI.

The autowt <branch-name> form is a convenient shortcut. Use the explicit switch command if your branch name conflicts with another autowt command (e.g., autowt switch cleanup).

Branch resolution¶

When creating a new worktree, autowt automatically:

1. Fetches the latest branches from your remote
2. Checks if the branch exists locally - if so, uses it
3. Checks if the branch exists on your remote (e.g., origin/branch-name) - if so, prompts to create a local worktree tracking the remote
4. If the branch doesn't exist anywhere, prompts to create a new branch from your repository's main branch (main or master)

Worktree directory organization¶

By default, worktrees are created in a dedicated directory adjacent to your main project. For example, if your project is in ~/dev/my-project, worktrees are created in ~/dev/my-project-worktrees/.

Branch names are sanitized for the filesystem - slashes become hyphens. For example, feature/user-auth creates a directory at ~/dev/my-project-worktrees/feature-user-auth/.

You can customize this with the directory_pattern setting (see Configuration), which supports template variables like {repo_name}, {branch}, {repo_parent_dir}, and environment variables. For example, to organize all worktrees in a central location: ~/.worktrees/{repo_name}/{branch}.

autowt ls¶

(Aliases: list, ll)

Lists all worktrees for the current project, indicating the main worktree, your current location, and any active terminal sessions. Running autowt with no arguments is equivalent to autowt ls.

The @ symbol indicates that there is an active terminal session for a worktree.

> autowt ls

  Worktrees:
→ ~/dev/my-project (main worktree)                         main ←
  ~/dev/my-project-worktrees/feature-new-ui @   feature-new-ui
  ~/dev/my-project-worktrees/hotfix-bug              hotfix-bug

autowt cleanup [WORKTREES...]¶

(Aliases: cl, clean, prune, rm, remove, del, delete)

Safely removes worktrees, their directories, and associated local git branches. By default, it launches an interactive TUI to let you select which worktrees to remove.

You can optionally specify one or more worktrees to remove by passing:

• Branch names (e.g., autowt cleanup feature-branch)
• Branch names without prefix (if you've configured branch_prefix)
• Paths to worktree directories (e.g., autowt cleanup ../my-project-worktrees/feature-branch)

When worktrees are specified, the command skips the interactive TUI and mode-based selection, and instead prompts for simple yes/no confirmation.

How cleanup works¶

When you run cleanup, autowt:

1. Identifies worktrees matching the selected mode criteria
2. Prompts for confirmation (shows list of worktrees to be removed)
3. Runs pre_cleanup Lifecycle Hooks if configured
4. Removes the worktree directories from your filesystem
5. Runs post_cleanup hooks if configured
6. Prompts to delete the associated local git branches (can be auto-confirmed with -y)

Note: Worktrees with uncommitted changes are automatically skipped in non-interactive modes unless you use --force.

autowt config¶

(Aliases: configure, settings, cfg, conf)

Opens an interactive TUI to configure global autowt settings, such as the default terminal mode. Learn more in the Configuration guide.

Global options¶

These options can be used with any autowt command.