Idempotent
Same directory, same port
Run trop reserve again from the same worktree and get the same number.
Learn moreRust CLI
trop
Port reservations for worktrees
A small CLI for stable localhost port numbers per worktree.
RustCLISQLiteWorktrees
Terminal
shell
$ cargo install trop-cli
$ PORT=$(trop reserve)
$ npm run dev -- --port $PORTReservation model
Same key, same port.
Reservations are keyed by directory and optional tag. Repeated calls return the same port.
What trop provides
Small guarantees for boring local ports
Tagged
Tags split services
Use --tag web, --tag api, or similar names when one worktree needs multiple ports.
Learn moreConcurrent
SQLite coordinates callers
Concurrent invocations share a local SQLite database.
Learn moreCleanup
Prune deleted worktrees
Remove reservations whose directories no longer exist.
Learn moreScope
Single-user coordination on one machine.
Non-goals
No system-wide enforcement. No multi-user broker. No container orchestration.
Documentation
Keep detailed guidance in Starlight.
Overview
What trop reserves, why it exists, and where it fits.
Open pageUsage
Basic commands and script patterns for local port reservations.
Open pageConfiguration
Port ranges, tags, exclusions, and cleanup behavior.
Open pageScope
What trop deliberately does and does not attempt to solve.
Open pageInstall
Replace the fixed port.
Use trop reserve where a script expects a port.
$ cargo install trop-cli
$ trop --version
$ PORT=$(trop reserve)