CLI reference

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.

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.

Rename a project everywhere it appears: .treeline.yml, the registry, and user-config keys (port reservations, editor themes and colors, including project/branch variants). Drops the old worktree databases and re-runs setup so each worktree comes back up under the new name with a freshly cloned DB. Names must match [a-zA-Z_][a-zA-Z0-9_]* (Postgres identifier rules); the command suggests a sanitized form when given an invalid name.

Create worktree + allocate resources + run setup in one step. --start boots the app after setup. --open opens in browser. 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.

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.

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.

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.

Re-allocate all worktrees with current config and reservations. Restarts supervised servers automatically.

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 --force to apply.

Read-only audit of the worktree registry. Reports orphans (entries pointing at directories that no longer exist) and other inconsistencies without changing anything.

Safe automatic repair: prunes orphaned entries after writing a backup of the previous registry. Pair with registry validate first.

Remove a single registry entry without freeing resources. For tooling integrations that need a surgical edit when release is too heavy.

Free allocated resources. --drop-db removes the cloned database. --remove-worktree deletes the directory. --all releases everything. Warns on unpushed commits.

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, detect framework, generate .treeline.yml if missing, run setup. Does not auto-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. --await blocks until TCP accepts on the port. On graceful exit, post_stop hooks run in reverse.

Stop the server process. Supervisor stays alive for resume with gtl start. --kill shuts down the supervisor entirely instead of keeping it alive.

Sync env, push updated vars to supervisor, restart server. Warns if commands.start differs from what the supervisor is running.

Print allocated port for the current worktree. For agents and scripts.

Open in browser: HTTPS branch URL when gtl serve is running, else http://localhost:{port}.

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.

Generate CA, trust it, add port forwarding (443 → router), register background service. Also upgrades an existing router. Details

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.

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.

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.)

Register a custom hostname on the router. From a worktree directory, port is auto-detected from the allocation. --remove <name> to unregister. Hot-reloaded within 5 seconds.

Remove service, port forwarding, and CA trust.

Write entries for all active routes to /etc/hosts. Required for Safari on macOS with localhost domain.

Remove managed entries from /etc/hosts.

Bind a well-known port and forward to the current worktree. Target defaults to the first allocated port. Details

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. 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.

Ephemeral share URL (token-gated Cloudflare or --tailscale for tailnet-only). Torn down on Ctrl+C.

Look up another project's base URL from the registry. Same-branch default; optional explicit branch.

Override {resolve:project} to a fixed branch. Regenerates env and restarts server. gtl link lists links.

Remove a link override.

Print env file. Treeline-managed keys marked [treeline]. --template shows unresolved tokens. gtl env defaults to show.

Re-read env from .treeline.yml, update env file, refresh editor.

Print the worktree's database name.

Drop and re-clone from template. --from overrides the source.

Drop and restore from a pg_dump file. Auto-detects format.

Drop the worktree's database without re-cloning.

Show all allocations. --check probes ports. --watch auto-refreshes. --json for structured output.

Interactive TUI (Bubble Tea). Browse worktrees by project with live updates. Aliases: gtl dash, gtl ui.

Interactive TUI picker. Arrow keys to navigate, Enter to print path. Alias: gtl wt.

Print filesystem path to a worktree by branch. project/branch to disambiguate.

Print the filesystem path of the current worktree. For scripting and agent tooling.

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).

Dump all user-level settings.

Read a setting by dot-notation key.

Write a setting and persist to disk.

Print config file location.

Open config in $EDITOR.

Re-apply editor title, color, and theme for the current worktree.

Print shell completion script. Includes dynamic completions for config keys and project names.

Start the MCP server (stdio transport). Used by editors, not invoked directly. See MCP setup.

Print the JSON config block for adding the Git Treeline MCP server to your editor. Supports --cursor, --vscode, --zed, and --windsurf.

Print version.