Docs / CLI
CLI reference
Invoked as git-treeline, git treeline, or gtl. All three are equivalent.
Verified against CLI v0.58.3
Setup
install
One command to get a developer productive. Creates .treeline.yml if
missing, creates user config, installs the post-checkout hook, allocates ports, writes env, and optionally
enables the local HTTPS router. Safe to re-run — every step is idempotent. Recommended over the
separate init → setup flow.
provision
Bring a host up to the repo’s declared baseline so that gtl setup can succeed. Reads the provision: section of .treeline.yml and runs an ordered, idempotent plan: apt packages, systemd services, language runtimes via mise, and template database hydration. Each step probes before acting, so re-running is a no-op. apt and services steps are Linux-only and skipped with a note on macOS. --dry-run prints the ordered plan without executing anything. See provision config.
init
Generate .treeline.yml with self-documenting template.
Auto-detects framework, writes AGENTS.md section, detects
editor. Project name is derived from git remote get-url origin (basename, .git stripped) and sanitized to a valid identifier — a fitter-app repo lands as fitter_app. Warns when config/database.yml has a non-identifier database name. Must be run inside a git repository; exits with an error otherwise.
rename <new-name>
Rename a project: updates .treeline.yml in the current branch and migrates user-config keys (port reservations, editor themes and colors, including project/branch variants), then prints the list of worktrees that need re-provisioning. Each worktree self-heals on the next gtl setup after rebasing — setup detects the name mismatch, drops the old database, releases the stale registry entry, and allocates fresh under the new name. Names must match [a-zA-Z_][a-zA-Z0-9_]* (Postgres identifier rules); the command suggests a sanitized form when given an invalid name.
new <branch>
Create worktree + allocate resources + run setup in one step. --start boots the app after setup. --open opens in browser. --no-setup creates the worktree without allocation, env files, or setup commands; run gtl setup later. Default base branch respects worktree_base from config. Works
without a .treeline.yml: detects framework and prompts to init
for server projects, or creates a plain worktree for non-server projects. Can be run from inside a worktree; prompts for confirmation unless --force is passed. If the configured template is missing, Treeline attempts to provision it, then falls back to an empty database with a warning. Use --strict to fail when a complete clone cannot be created.
claim <branch>
Fetch an existing branch from origin, create or reuse its worktree, and fast-forward it when possible. Diverged branches are left unchanged with a warning. Prints only the worktree path to stdout for scripts. --path selects the destination; --no-setup skips explicit provisioning of a newly created worktree, but installed Git hooks can still run setup. Existing worktrees are still provisioned.
review <[#]PR#>
Fetch a GitHub PR into a new worktree with full setup. Requires gh CLI. From inside a worktree, prompts to switch the current worktree to the PR branch. Leading # is accepted (gtl review '#42'). --no-setup defers allocation, env files, and setup for a newly created worktree.
switch <branch-or-[#]PR#>
Switch a worktree to a different branch or PR. Fetches, checks out, updates registry, refreshes env. --setup re-runs setup commands. --restart bounces the supervised server. Leading # on PR numbers is accepted.
setup [path]
Full provisioning: allocate ports, copy files, write env, clone DB, run setup commands. Idempotent. When reusing an allocation, verifies ports are still free and valid; if not, re-allocates and warns. If a setup command fails the worktree is preserved (not removed); exits with code 2 so callers can distinguish a setup failure from other errors.
refresh
Re-allocate all worktrees with current config and reservations. Restarts supervised servers automatically.
reallocate [paths...]
Bulk re-runs setup across many worktrees. Three modes: explicit paths, --from <dir> to scan a Conductor-style layout, or --all-registry for every entry whose directory still exists. Defaults to dry-run; pass --apply to run setup.
registry validate
Read-only audit of the worktree registry. Reports orphans (entries pointing at directories that no longer exist) and other inconsistencies without changing anything. --json emits structured output for tooling.
registry repair
Safe automatic repair: prunes orphaned entries after writing a backup of the previous registry. Pair with registry validate first.
registry forget <path>
Remove a single registry entry without freeing resources. For tooling integrations that need a surgical edit when release is too heavy.
release [path]
Free allocated resources. --drop-db removes the cloned database. --remove-worktree deletes the directory — works on unmanaged worktrees (created with git worktree add directly), respects --force and --dry-run. --all releases everything. Warns on unpushed commits. Release hooks run on every release path; --force overrides hook failures.
prune
Clean orphaned allocations. --stale: worktrees whose directory no
longer exists (distinguishes worktrees from standalone clones, so Conductor-style layouts aren’t pruned by mistake). --merged: branches merged to merge_target.
clone <repo>
Clone, detect framework, generate .treeline.yml if missing, run
setup. Does not auto-start.
nuke
Machine-wide recovery. Stops all supervised servers, kills any stale supervisor processes, and cleans up orphaned state across all projects registered on this machine. Prompts for confirmation; pass --force to skip. --dry-run shows what would be affected without acting.
Server management
start
Fresh start (no supervisor): runs start hooks, syncs env, refreshes editor, launches supervisor. Resume (supervisor
alive): sends start signal. No env sync, no hooks. If a server is already running in another terminal,
prompts interactively to stop it, restart under the new terminal, or cancel — non-TTY callers (agents, pipes) get a plain error. --await blocks
until TCP accepts on the port. On graceful exit, post_stop hooks run
in reverse.
stop
Stop the server process. Supervisor stays alive for resume with gtl start. --kill shuts down the supervisor entirely instead of keeping it alive.
restart
Sync env, push updated vars to supervisor, restart server. Warns if commands.start differs from what the supervisor is running.
open
Open in browser: HTTPS branch URL when gtl serve is running, else http://localhost:{port}.
routes
Print the routing URLs for all allocated ports. Shows HTTPS URLs via the router when running, otherwise localhost fallback. Also shows the tunnel URL if configured.
Networking
See Networking guide for architecture and design rationale.
serve install
Generate CA, trust it, add port forwarding (443 → router), register background service. Also upgrades an existing router. Details
serve status
Show router state, CA status, port forwarding, and all active routes. Reads pf state from the kernel rather than pf.conf on disk, so “active” means actually loaded. The router self-heals pf.conf if a macOS update reverts it. A router reachable only via the 443 port forward is treated as alive.
serve restart
Fast bounce of the running router via launchctl kickstart -k (macOS) or systemctl --user restart (Linux). No sudo, no plist rewrite. Use after upgrading the CLI to pick up the new binary. --if-installed exits 0 silently when no router service is registered — safe for tooling and brew post_install.
serve reload-pf
Targeted pfctl reload for the port-forwarding rules only. Use after a reboot dropped pf without paying the cost of a full serve install. (Most users won’t need this — v0.40.1 installs a LaunchDaemon that re-applies rules at boot.)
serve alias [name] [port]
Add, remove, or list static subdomain aliases on the router. From a worktree directory, port is auto-detected from the allocation. Pass --remove to unregister. With no arguments, lists all aliases. Hot-reloaded within 5 seconds.
serve logs
Stream or print recent router logs. Useful for diagnosing routing failures and TLS errors without tailing a file manually.
serve uninstall
Remove service, port forwarding, and CA trust.
serve hosts sync
Write entries for all active routes to /etc/hosts. Required for Safari on macOS with localhost domain.
serve hosts clean
Remove managed entries from /etc/hosts.
proxy <port> [target]
Bind a well-known port and forward to the current worktree. Target defaults to the first allocated port. --tls enables TLS termination with HTTP/2 support. Details
tunnel [port]
Public HTTPS via Cloudflare. Subcommands: tunnel setup for named
configs, tunnel status for connection state, tunnel default to set the active tunnel, tunnel remove to delete, tunnel reset to clear all tunnel state (configs, certs, credentials) — accepts -y to skip confirmation. Concurrent
invocations on the same named tunnel multiplex through a lazy-start per-tunnel daemon, so multiple worktrees
can share one cloudflared with merged multi-host ingress.
share [port]
Ephemeral share URL (token-gated Cloudflare or --tailscale for
tailnet-only). Torn down on Ctrl+C.
Cross-worktree
resolve <project> [branch]
Look up another project's base URL from the registry. Same-branch default; optional explicit branch.
link <project> <branch>
Override {resolve:project} to a fixed branch. Regenerates env and
restarts server. gtl link lists links.
unlink <project>
Remove a link override.
relate <path>
Create a durable relationship between the current worktree and another worktree at <path>. Relationships persist in the registry and appear in status --json as related[].
unrelate <path>
Remove a cross-worktree relationship.
Environment & database
env show
Print env file. Treeline-managed keys marked [treeline]. --template shows unresolved tokens. gtl env defaults to show.
env sync
Re-read env from .treeline.yml, update env file, refresh editor.
db pull <env>
Resolve a remote source from database.sources in .treeline.yml (via: fly, via: heroku, or via: env), pg_dump it, and restore into the worktree database. The dump is retained locally — run db refresh to reset from it without re-downloading. Refuses to overwrite the main worktree's template database.
db refresh [env]
Drop and re-import from a previously pulled sample. No network access. With no argument, refreshes from the most recently pulled env. Refuses to overwrite the main worktree's template database.
db template update
Advance the root template database: fetches merge_target from origin and runs commands.migrate in a temporary detached checkout. Requires Git 2.29+ and an env mapping using {database}, {database.name}, or {database_1} to target the root template. Setup commands and hooks do not run; migration dependencies must be available or prepared by the migration command. Existing checkout branches and worktree databases stay unchanged. Run gtl db reset in a worktree to re-clone. See the template update guide.
db reset
Drop and re-clone from template. --from overrides the source. Prompts for confirmation; pass --force to skip or --dry-run to preview.
db restore <file>
Drop and restore from a pg_dump file. Auto-detects format. Prompts for confirmation; pass --force to skip.
db drop
Drop the worktree's database without re-cloning. Prompts for confirmation; pass --force to skip.
Navigation & status
status
Show all allocations. --check probes ports. --watch auto-refreshes. --json for structured output; includes a related[] array of cross-worktree relationships.
dashboard
Interactive TUI (Bubble Tea). Browse worktrees by project with live updates. Aliases: gtl dash, gtl ui.
worktrees
Interactive TUI picker. Arrow keys to navigate, Enter to print path. Alias: gtl wt.
where <branch>
Print filesystem path to a worktree by branch. project/branch to
disambiguate.
worktree
Print the filesystem path of the current worktree. For scripting and agent tooling.
doctor
Check config, allocation, runtime, and framework diagnostics. Verifies the listener PID against launchd’s registered PID, probes /_treeline/health, reads pf state from the kernel, and surfaces a Request-flow section that walks the chain end-to-end and points at the first failure. --fix auto-runs the remediations the doctor was already printing as hints (router restart, pf reload, registry prune for orphans).
Config & editor
config list
Dump all user-level settings.
config get <key>
Read a setting by dot-notation key.
config set <key> <value>
Write a setting and persist to disk.
config path
Print config file location.
config edit
Open config in $EDITOR.
editor refresh
Re-apply editor title, color, and theme for the current worktree.
completion bash|zsh|fish|powershell
Print shell completion script. Works for all three invocation forms (gtl, git-treeline, git treeline). Includes dynamic completions for config keys and project names.
Agent integration
mcp-config
Print the MCP server config block for all supported editors (Cursor, Claude Code, and more). Copy the relevant snippet into your editor's MCP config.
version
Print version. --json outputs {"cli": "0.43.15", "router": "0.43.15"} — or "router": null when no router is running. Designed as a stable contract for tooling to read the running router version without scraping human-readable output.
update
Update the CLI to the latest release. Version-aware: checks the current version against the latest available and skips the download if already up to date. When a newer version is available but you haven’t run gtl update, GTL passively notifies you after commands complete.
Related
- Configuration reference: every
.treeline.ymlfield and user config key. - Hooks guide: start hooks lifecycle and edge cases.
- Networking guide: port allocation, routing, aliases, proxy, tunnels.