band repos

The band repos command group manages the repos registered with Band. A repo is a directory on your filesystem — typically a Git repository — that you've registered with Band so it can create worktrees inside it.

List repos

Display all registered repos.

band repos list

Example output:

NAME        PATH                         WORKTREES
my-app      /Users/dev/repos/my-app   3 worktrees
api-server  /Users/dev/repos/api      1 worktree
docs-site   /Users/dev/repos/docs     0 worktrees

Add a repo

Register a directory as a Band repo. The path must point to an existing Git repository. The repo name is derived from the directory name unless you pass --label.

band repos add /Users/dev/repos/my-app
band repos add . --label "Frontend"

Band reads .band/config.json from the repo directory if it exists. If the config file is missing, the repo is still registered and you can add the file later.

Remove a repo

Unregister a repo by name. This does not delete the directory on disk — it only removes the repo (and any tracked worktrees) from Band's database.

band repos remove my-app

JSON output

All subcommands support --output json for machine-readable output.

band repos list --output json

Example JSON output:

{
  "repos": [
    {
      "name": "my-app",
      "path": "/Users/dev/repos/my-app",
      "worktreeCount": 3
    },
    {
      "name": "api-server",
      "path": "/Users/dev/repos/api",
      "worktreeCount": 1
    }
  ]
}

Notes

• Repo names default to the basename of the directory; pass --label to override.
• Repo names must be unique. Adding a directory whose name conflicts with an existing repo will fail.
• Repos are stored in Band's local SQLite database (~/.band/band.db).
• The repo directory should be a Git repository for worktree features (worktrees, diff, branch status) to work.