npm package: @octavian-tocan/wt-cli
Description: Git worktree manager with setup, health checks, repair, and shell-native switching
Author: Octavian Tocan
Latest version: 0.1.0

# wt-cli

`wt-cli` is a config-driven git worktree manager for repos that need more than `git worktree add`.

It gives you one place to create worktrees, hydrate them, check their health, repair drift, clean them up, and jump between them from your shell.

## What it does

- creates local, remote-tracking, or brand-new branch worktrees
- runs repo-specific setup steps after creation
- checks whether a worktree is actually ready to use
- repairs unhealthy worktrees by pruning and rerunning setup
- emits shell helpers so `wt go feature/foo` really changes directories
- supports machine-readable `--json` output for scripts and automation

## Install

```bash
pnpm add -D @octavian-tocan/wt-cli
```

If you want a repo-local shortcut, add this to `package.json`:

```json
{
  "scripts": {
    "wt": "wt"
  }
}
```

## Quick start

Initialize config in a repo:

```bash
pnpm exec wt init
```

Create a worktree and hydrate it automatically:

```bash
pnpm exec wt create feature/search-polish
```

Check what exists:

```bash
pnpm exec wt list
pnpm exec wt status
pnpm exec wt doctor
```

## Commands

- `wt create <branch>` - create a worktree and optionally auto-setup it
- `wt go <branch>` - resolve a worktree path for shell switching
- `wt list` - list all worktrees
- `wt status` - show a status overview
- `wt setup [branch|path]` - run setup steps for a worktree
- `wt sync-env` - rerun configured copy steps across worktrees
- `wt clean` - remove merged, stale, or orphaned worktrees
- `wt doctor` - inspect worktree health and readiness
- `wt repair` - prune and rehydrate unhealthy worktrees
- `wt exec <branch> -- <command>` - run a command inside a worktree
- `wt init` - scaffold `wt.config.json`
- `wt shell init zsh|bash|fish` - emit shell integration

## Shell integration

To make `wt go foo` change the current shell directory instead of printing a path:

```bash
eval "$(pnpm exec wt shell init zsh)"
```

If `wt` is installed globally, `wt shell init zsh` works too. The generated helper falls back to `pnpm exec wt` or `npx wt` when the binary is not already on your `PATH`.

## Config

`wt-cli` reads config from the first source it finds:

1. `wt.config.json`
2. `package.json#wt`

Example:

```json
{
  "worktreeDir": "tree",
  "mainBranch": "main",
  "defaultBase": "main",
  "remote": "origin",
  "autoSetup": true,
  "staleDays": 30,
  "setup": {
    "steps": [
      { "type": "install", "command": "auto" },
      {
        "type": "copy",
        "from": ".env*",
        "to": ".",
        "exclude": [".env.example"],
        "optional": true
      },
      { "type": "run", "command": "pnpm run build:packages" },
      {
        "type": "verify",
        "path": "node_modules",
        "label": "Dependencies installed"
      }
    ]
  },
  "lifecycleScripts": {
    "postsetup": "wt:postsetup",
    "preclean": "wt:preclean"
  }
}
```

### Setup step types

- `install` - install dependencies with auto-detection or an explicit command
- `copy` - copy files from the main worktree into the target worktree
- `run` - run an arbitrary command inside the worktree
- `verify` - assert that a path exists after setup

## Canonical config only

`wt-cli` no longer supports the older `.worktree-manager.json` format or legacy config keys like `buildCommand`, `excludeEnvFiles`, and `verifyPaths`. Use `wt.config.json` or `package.json#wt` with the canonical `setup.steps` model.