| name | port-cli |
| description | Use when managing git worktrees and local services with the Port CLI, including setup, entering worktrees, running Docker Compose or host processes, viewing URLs/status, and cleaning up safely.
|
Port CLI
Port is a CLI for managing git worktrees that makes it easy to create, enter, and tear down parallel working copies of your repo. When those worktrees run Docker Compose services, Port can automatically stand up a Traefik reverse proxy so every worktree can bind the same ports without conflicts — each accessed via its own hostname (e.g., feature-1.port:3000).
Safety Rules
- Inspect state before changing it: prefer
port status, port list, and
port urls first.
- Ask before privileged machine setup with
port install or port uninstall.
- Ask before destructive cleanup:
port remove, port prune, and
port cleanup can delete worktrees, branches, containers, volumes, or
images.
- Do not read or print secret environment files while troubleshooting Port projects.
- If shell integration is not installed,
port enter and port exit may
print a cd command instead of changing the current shell directory.
First-Time Setup
Use this workflow when a repository has not been prepared for Port yet:
port onboard
port init
port install
Then add shell integration to the user's shell profile:
eval "$(port shell-hook bash)"
eval "$(port shell-hook zsh)"
port shell-hook fish | source
Command Reference
These commands are generated from src/lib/commandGuide.ts, the same
metadata used by onboarding docs and command coverage tests.
port init
Initialize .port/ directory structure
- How: Run in your repository root if setup has not been done yet (check with port status first).
- Why: Creates .port config, hooks, and worktree directories.
- Agent guidance: Use during first-time setup before starting services in a repository.
port onboard
Print recommended workflow and command usage guide
- How: Run when a user wants a guided overview, or use
port onboard --md to regenerate ONBOARD.md.
- Why: Shows the recommended Port workflow from the shared command metadata.
- Agent guidance: Prefer this when introducing Port to a repository or checking the canonical workflow.
port install (privileged)
Set up DNS for wildcard domain (default from config)
- How: Run once per machine (or when changing domain/IP).
- Why: Configures wildcard DNS so branch domains resolve locally.
- Agent guidance: Ask before running because this can require administrator privileges and changes machine DNS.
port list
Print worktree names, one per line
- How: Run when you need a compact list of known worktrees. Alias: port ls.
- Why: Shows which worktrees Port knows about without changing state.
- Agent guidance: Safe read-only inspection command; prefer before cleanup or branch selection.
- Aliases:
port ls
port status
Show service status across all worktrees
- How: Run anytime when you need service-level visibility.
- Why: Shows running/stopped services across all worktrees.
- Agent guidance: Use before changing service state or diagnosing routing problems.
port shell-hook <bash|zsh|fish>
Print shell integration code for automatic cd
- How: Add eval "$(port shell-hook bash)" to your shell profile (one-time setup).
- Why: Enables port enter/exit to change your shell directory automatically.
- Agent guidance: Recommend this for interactive users; without it, enter/exit prints cd commands.
port completion <bash|zsh|fish>
Generate shell completion script for tab completion
- How: Run once to generate shell completion script (bash, zsh, or fish).
- Why: Enables tab completion for port commands and options.
- Agent guidance: Optional convenience setup; safe because it only prints shell code.
port enter <branch>
Enter a worktree explicitly (including command names)
- How: Use explicit enter, especially when branch names match commands or are already checked out elsewhere.
- Why: Creates or enters the branch worktree and changes into it, reusing an existing checked-out worktree when needed.
- Agent guidance: Prefer explicit enter when branch names collide with commands such as status, install, or remove.
port <branch>
Enter a worktree (creates if it does not exist)
- How: Use as shorthand when the branch name does not match a Port command.
- Why: Creates or enters a branch worktree quickly.
- Agent guidance: Avoid this shorthand when the branch name might collide with a command; use port enter instead.
port exit
Exit the current worktree and return to repo root
- How: Run to return to the repository root from a worktree.
- Why: Changes back to the repo root and clears PORT_WORKTREE env var.
- Agent guidance: Safe navigation command. Shell integration may be required to change the caller shell directory.
port up [services...]
Start docker-compose services in current worktree
- How: Run inside a worktree after entering it. Omit services to start everything, or pass specific service names to start a subset and their dependencies.
- Why: Starts services and wires routing through Traefik.
- Agent guidance: Use inside a Port worktree after setup; then run port urls to inspect service URLs.
port down [services...]
Stop docker-compose services and host processes selectively
- How: Run in a worktree when you want to stop everything or selectively remove a subset of services while leaving the rest running.
- Why: Stops services and removes the selected containers without tearing down the whole worktree.
- Agent guidance: Ask if stopping services may interrupt the user; safer than removing the whole worktree.
port urls [service]
Show service URLs for the current worktree
- How: Run in a worktree or repository root.
- Why: Shows the exact branch URLs to open and share.
- Agent guidance: Read-only; use after port up or port run to find the right URL.
port open
Re-run the post-up hook in the current repo/worktree context
- How: Run after port up [services...] if you want to trigger your post-up workflow manually.
- Why: Re-runs the post-up hook (for example, open the browser to your branch URL).
- Agent guidance: Use when the user wants the post-up workflow repeated without restarting services.
port compose [args...]
Run docker compose with automatic -f flags for this worktree
- How: Alias: port dc. Run inside a worktree to run docker compose commands.
- Why: Automatically applies -f flags for the worktree's compose files.
- Agent guidance: Use instead of raw docker compose when operating on a Port-managed worktree.
- Aliases:
port dc
port run <port> -- <command...>
Run a host process with Traefik routing
- How: Run inside a worktree for non-Docker development servers that honor the PORT environment variable.
- Why: Starts a host process on an available port and routes the logical port through Traefik.
- Agent guidance: Confirm the command respects PORT; use port kill to stop services started this way.
port kill [port]
Stop host services (optionally by logical port)
- How: Run when you need to stop host processes started with port run.
- Why: Stops host services listed in Port state, optionally narrowed to one logical port.
- Agent guidance: Ask before stopping a process that may be in active use.
port hook [hook-name]
Re-run a hook script in the current worktree
- How: Use
port hook --list to inspect hooks, or port hook <hook-name> to run one.
- Why: Lets users inspect or manually re-run Port lifecycle hooks.
- Agent guidance: List hooks first when unsure; hooks can execute project-defined scripts.
port rename <branch>
Rename the current worktree and branch in place
- How: Run inside a worktree after stopping its services. Alias: port mv .
- Why: Renames the current worktree and branch while keeping Port state aligned.
- Agent guidance: Ask first because this changes Git branch/worktree names.
- Aliases:
port mv
port remove <branch> (destructive)
Remove worktree, archive branch, clean up Docker resources
- How: Use after a branch is done.
- Why: Stops services, removes worktree, and archives the local branch.
- Agent guidance: Ask before running; use --keep-branch if the local branch should remain.
- Aliases:
port rm
port prune (destructive)
Remove worktrees for branches that have been merged
- How: Start with
port prune --dry-run; use --force only after confirming candidates.
- Why: Cleans up worktrees whose branches have already been merged.
- Agent guidance: Always prefer --dry-run first because this removes worktrees.
port cleanup (destructive)
Delete archived branches created by port remove
- How: Run after reviewing archived branches. Use --cleanup-images only when explicitly requested.
- Why: Deletes archived local branches created by port remove and can optionally clean images.
- Agent guidance: Ask before running; Docker image cleanup is opt-in and can remove shared cache layers.
port uninstall (privileged, destructive)
Remove DNS configuration for wildcard domain used by this repo
- How: Run when the user explicitly wants to remove Port DNS setup for a domain.
- Why: Removes machine-level DNS configuration created by port install.
- Agent guidance: Ask before running because this can require administrator privileges and changes machine DNS.
Troubleshooting Checklist
- Run
port status to see known worktrees and services.
- Run
port urls inside the worktree to confirm expected hostnames.
- Verify Docker and Docker Compose are available when using
port up.
- If domains do not resolve, confirm
port install has been run for the
configured domain.
- If a branch name matches a Port command, use
port enter <branch> instead
of port <branch>.
- For host processes, confirm the command respects the
PORT environment
variable.
Reference
