band projects

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

List projects

Display all registered projects.

band projects list

Example output:

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

Add a project

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

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

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

Remove a project

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

band projects remove my-app

JSON output

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

band projects list --output json

Example JSON output:

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

Notes

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