band projects

The band projects command group manages the projects registered with Band. A project is a directory on your filesystem that contains a codebase — typically a Git repository with a .band/config.json file.

List Projects

Display all registered projects.

band projects list

Example output:

ID   Name        Path                          Workspaces
1    my-app      /Users/dev/projects/my-app     3
2    api-server  /Users/dev/projects/api        1
3    docs-site   /Users/dev/projects/docs       0

Add a Project

Register a directory as a Band project. The path must point to an existing directory.

band projects add /Users/dev/projects/my-app

Band will read the .band/config.json file from the project directory if it exists. If the config file is not present, the project is still registered and can be configured later.

band projects add .
# Adds the current directory as a project

Remove a Project

Unregister a project by its ID. This does not delete the directory or any files — it only removes the project from Band's database.

band projects remove 1

Any workspaces associated with the project will also be removed from Band. The underlying Git worktrees on disk are not deleted automatically.

JSON Output

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

band projects list --output json

Example JSON output:

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

Notes

• Project names are derived from the directory name by default.
• Each project path must be unique — you cannot register the same directory twice.
• Projects are stored in Band's local SQLite database.
• The project directory should be a Git repository for workspace features to work properly.