Skip to main content

Command Reference

Manage git worktree development workspaces.

Usage:

$ bonsai [OPTIONS] COMMAND [ARGS]...

Options:

  • --version: Show the version and exit.
  • -h, --help: Show this message and exit.

Commands:

  • clone: Clone a repository into a new Bonsai workspace.
  • start-here: Guide a newcomer from clone to a running app in one sequenced flow.
  • init: Create a starter .bonsai.toml for the current checkout or workspace.
  • adopt: Convert the current single-folder checkout into a Bonsai workspace in place.
  • add: Prepare a managed worktree for a branch.
  • remove: Remove a managed worktree.
  • move: Move a managed worktree folder.
  • checkout: Resolve or prepare a worktree for shell checkout.
  • open: Open a worktree's primary local URL.
  • urls: Show configured local URLs and route diagnostics.
  • context: Print Bonsai facts for the current worktree (alias of status).
  • shell-init: Print shell integration code.
  • install-shell: Install shell integration for Bonsai checkout.
  • list: List managed worktrees in the current workspace.
  • ps: List tracked Bonsai app processes across registered workspaces.
  • ports: List configured service ports and listener ownership.
  • status
  • start: Run the configured start command in a worktree.
  • up: Start the configured app command in the background and track its PID.
  • mux: Start configured service commands in panes of the detected multiplexer.
  • tmux: Start configured service commands in a deterministic tmux session.
  • stop: Stop listener processes for configured service ports.
  • restart: Stop matching listeners, then run the configured start command.
  • exec: Run a command in one worktree with its generated environment.
  • each: Run a command sequentially across Bonsai worktrees.
  • logs
  • sync: Compare or repair generated Bonsai files.
  • repair
  • repair-ports: Plan or apply slot reassignments for worktrees with conflicting ports.
  • cleanup: Remove branch worktrees whose pull requests were merged.
  • doctor: Check workspace health and report repair hints.

bonsai clone​

Clone a repository into a new Bonsai workspace.

Usage:

$ bonsai clone [OPTIONS] <git_url> <name>

Arguments:

  • <git_url>
  • <name>

Options:

  • --interactive: Create .bonsai.toml interactively when missing.
  • --no-interactive
  • --worktree-location <location>: Where to create worktrees: local, global, or siblings.
  • -h, --help: Show this message and exit.

bonsai start-here​

Guide a newcomer from clone to a running app in one sequenced flow.

Usage:

$ bonsai start-here [OPTIONS] <git_url> <name>

Arguments:

  • <git_url>
  • <name>

Options:

  • --branch <branch>: Branch to prepare as the first worktree.
  • --shell <shell>: Shell to offer integration for. [default: zsh]
  • --worktree-location <location>: Where to create worktrees: local, global, or siblings.
  • --interactive: Run guided prompts and gate the final URL on a liveness probe. Use --no-interactive for a scripted run that prints the resolved URL.
  • --no-interactive
  • -h, --help: Show this message and exit.

bonsai init​

Create a starter .bonsai.toml for the current checkout or workspace.

Usage:

$ bonsai init [OPTIONS]

Options:

  • --force: Overwrite an existing .bonsai.toml.
  • -h, --help: Show this message and exit.

bonsai adopt​

Convert the current single-folder checkout into a Bonsai workspace in place.

Usage:

$ bonsai adopt [OPTIONS]

Options:

  • --dry-run: Preview the conversion and warnings without changing anything.
  • --yes: Convert without prompting (required when not attached to a terminal).
  • --undo: Reverse the most recent in-place conversion in this folder.
  • -h, --help: Show this message and exit.

bonsai add​

Prepare a managed worktree for a branch.

Usage:

$ bonsai add [OPTIONS] [branch]

Arguments:

  • [branch]

Options:

  • --pr <pr_number>: Prepare a worktree for a GitHub pull request.
  • --force: Allow closed or merged pull requests with --pr.
  • --base-branch <base_branch>: Base branch to use when creating a new branch worktree.
  • --editor: Open the prepared worktree in an editor.
  • --open: Open the prepared worktree's primary local URL.
  • --start: Run the configured start command after add.
  • -h, --help: Show this message and exit.

bonsai remove​

Remove a managed worktree.

Usage:

$ bonsai remove [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --force: Remove a worktree with uncommitted changes.
  • -h, --help: Show this message and exit.

bonsai move​

Move a managed worktree folder.

Usage:

$ bonsai move [OPTIONS] <name> <new_folder>

Arguments:

  • <name>
  • <new_folder>

Options:

  • --force: Rename the default worktree (relocates the main tree, repairs secondaries).
  • -h, --help: Show this message and exit.

bonsai checkout​

Resolve or prepare a worktree for shell checkout.

Usage:

$ bonsai checkout [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --path: Print the resolved worktree path for shell integration.
  • --base-branch <base_branch>: Base branch to use when creating a new branch worktree.
  • --pr <pr_number>: Prepare and resolve a GitHub pull request worktree.
  • --force: Allow closed or merged pull requests with --pr.
  • -h, --help: Show this message and exit.

bonsai open​

Open a worktree's primary local URL.

Usage:

$ bonsai open [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --service <service>: Open a specific public service URL.
  • --interactive: Launch a browser after confirming the URL responds. Use --no-interactive to print the resolved URL without probing.
  • --no-interactive
  • --label <label>: Open through the configured browser extension with a tab label.
  • -h, --help: Show this message and exit.

bonsai urls​

Show configured local URLs and route diagnostics.

Usage:

$ bonsai urls [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --service <service_name>: Filter diagnostics to one public service.
  • --diagnose <diagnose_url>: Find diagnostics for a specific configured URL.
  • --format <output_format>: Output format: text or json. [default: text]
  • -h, --help: Show this message and exit.

bonsai context​

Print Bonsai facts for the current worktree (alias of status).

Usage:

$ bonsai context [OPTIONS]

Options:

  • --format <output_format>: Output format: text or json. [default: text]
  • -h, --help: Show this message and exit.

bonsai shell-init​

Print shell integration code.

Usage:

$ bonsai shell-init [OPTIONS] <shell>

Arguments:

  • <shell>

Options:

  • -h, --help: Show this message and exit.

bonsai install-shell​

Install shell integration for Bonsai checkout.

Usage:

$ bonsai install-shell [OPTIONS] <shell>

Arguments:

  • <shell>

Options:

  • -h, --help: Show this message and exit.

bonsai list​

List managed worktrees in the current workspace.

Usage:

$ bonsai list [OPTIONS]

Options:

  • --format <output_format>: Output format: text or json. [default: text]
  • --all: List registered workspaces.
  • -h, --help: Show this message and exit.

bonsai ps​

List tracked Bonsai app processes across registered workspaces.

Usage:

$ bonsai ps [OPTIONS]

Options:

  • --format <output_format>: Output format: text or json. [default: text]
  • -h, --help: Show this message and exit.

bonsai ports​

List configured service ports and listener ownership.

Usage:

$ bonsai ports [OPTIONS]

Options:

  • --format <output_format>: Output format: text or json. [default: text]
  • --busy: Only show ports that currently have listeners.
  • -h, --help: Show this message and exit.

bonsai status​

Usage:

$ bonsai status [OPTIONS]

Options:

  • --format <output_format>: Output format: text or json. [default: text]
  • -h, --help: Show this message and exit.

bonsai start​

Run the configured start command in a worktree.

Usage:

$ bonsai start [OPTIONS] [branch]

Arguments:

  • [branch]

Options:

  • -h, --help: Show this message and exit.

bonsai up​

Start the configured app command in the background and track its PID.

Usage:

$ bonsai up [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --wait-timeout <wait_timeout>: Seconds to wait for the primary service port. [default: 30.0]
  • -h, --help: Show this message and exit.

bonsai mux​

Start configured service commands in panes of the detected multiplexer.

Usage:

$ bonsai mux [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --detach: Create or report the session without attaching.
  • --backend <backend>: Multiplexer backend: auto, tmux, herdr, or cmux. auto picks herdr or cmux when bonsai runs inside one, otherwise tmux. [default: auto]
  • -h, --help: Show this message and exit.

bonsai tmux​

Start configured service commands in a deterministic tmux session.

Usage:

$ bonsai tmux [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --detach: Create or report the tmux session without attaching.
  • -h, --help: Show this message and exit.

bonsai stop​

Stop listener processes for configured service ports.

Usage:

$ bonsai stop [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --all: Stop matching listeners for all worktrees.
  • --force: Stop external or unknown owners of selected ports.
  • -h, --help: Show this message and exit.

bonsai restart​

Stop matching listeners, then run the configured start command.

Usage:

$ bonsai restart [OPTIONS] [name]

Arguments:

  • [name]

Options:

  • --force: Stop external or unknown owners before starting.
  • --detach: Start in the background after stopping.
  • --wait-timeout <wait_timeout>: Seconds to wait for detached readiness. [default: 30.0]
  • -h, --help: Show this message and exit.

bonsai exec​

Run a command in one worktree with its generated environment.

Usage:

$ bonsai exec [OPTIONS] [args...]

Arguments:

  • [args...]

Options:

  • -h, --help: Show this message and exit.

bonsai each​

Run a command sequentially across Bonsai worktrees.

Usage:

$ bonsai each [OPTIONS] [args...]

Arguments:

  • [args...]

Options:

  • --skip-default: Run only managed worktrees.
  • -h, --help: Show this message and exit.

bonsai logs​

Usage:

$ bonsai logs [OPTIONS] [branch]

Arguments:

  • [branch]

Options:

  • --command <command>: Filter logs by lifecycle command kind.
  • -f, --follow: Follow the selected log file.
  • -h, --help: Show this message and exit.

bonsai sync​

Compare or repair generated Bonsai files.

Usage:

$ bonsai sync [OPTIONS]

Options:

  • --apply: Write regenerated files.
  • -h, --help: Show this message and exit.

bonsai repair​

Usage:

$ bonsai repair [OPTIONS]

Options:

  • --apply: Write repaired workspace state.
  • -h, --help: Show this message and exit.

bonsai repair-ports​

Plan or apply slot reassignments for worktrees with conflicting ports.

Usage:

$ bonsai repair-ports [OPTIONS]

Options:

  • --format <output_format>: Output format: text or json. [default: text]
  • --apply: Write repaired slots and sync files.
  • -h, --help: Show this message and exit.

bonsai cleanup​

Remove branch worktrees whose pull requests were merged.

Usage:

$ bonsai cleanup [OPTIONS]

Options:

  • --apply: Remove eligible worktrees.
  • --force: Remove eligible worktrees with uncommitted changes.
  • -h, --help: Show this message and exit.

bonsai doctor​

Check workspace health and report repair hints.

Usage:

$ bonsai doctor [OPTIONS]

Options:

  • --format <output_format>: Output format: text or json. [default: text]
  • --apply: Apply safe workspace repairs.
  • --preflight: Check first-run prerequisites without a workspace.
  • -h, --help: Show this message and exit.