Skip to content

Getting started

Run a second branch without sharing the first branch's ports or database. Install the CLI, configure your existing project, then create a worktree.

Verified against CLI v0.58.3. Upgrading an existing installation?

You'll need macOS or Linux, Git, and your project's runtimes and dependencies. For database cloning, prepare a PostgreSQL template database or SQLite file. Containers are optional.

1. Install the CLI

With Homebrew on macOS or Linux:

brew install git-treeline/tap/git-treeline

Go install or download a binary

With Go 1.26 or later:

go install github.com/git-treeline/cli/cmd/git-treeline@latest

Or download a binary from the releases page.

Homebrew installs both git-treeline and the gtl alias used below. Go install provides git-treeline; use that command in place of gtl. It also works as git treeline.

2. Configure your project

cd ~/myapp
gtl install

Treeline detects supported frameworks, creates .treeline.yml if needed, installs a Git hook, and allocates resources for the current checkout. Review the generated setup and start commands for your app.

Local HTTPS is optional. Accepting the router setup requires administrator authorization to trust a local certificate and configure forwarding. Skip it to use localhost; you can run gtl serve install later.

For an annotated config and framework-specific setup, follow the full setup walkthrough.

3. Create and start a worktree

gtl new feature-auth --start

This creates the worktree, allocates its ports, writes its env file, runs your setup commands, and starts the configured server. If database cloning is configured, the worktree gets its own copy of the template. A named HTTPS URL requires the optional router.

Open another terminal in the new worktree and run gtl doctor to check its configuration and runtime. To review a GitHub PR instead, use gtl review 42 --start from the main checkout; this requires the GitHub CLI.

Choose what you need next

  • Database isolation — PostgreSQL cloning, SQLite copies, and template updates.
  • Networking — local HTTPS names, stable callback ports, and public tunnels.
  • Lifecycle — switch branches, start and stop servers, and release resources.
  • AI agents — give agents access to real allocations and server controls.

Upgrading to v0.58.3

Run gtl update, then gtl version to confirm the installed version. See the release notes for all changes.

Template updates now run in a temporary detached checkout, leaving your primary checkout unchanged. They require Git 2.29 or later and an explicit primary database mapping in env. Review the template update requirements before using database.sync_on_create or gtl db template update.

Coming from v0.58.0 or earlier? Stop each older supervisor with gtl stop --kill from the same directory path used to launch it (including any symlink alias), then run gtl start. Ctrl+C in its original terminal also works.