Usage

Install

With Rust and Cargo installed:

cargo install trop-cli

The package is trop-cli; the installed command is trop.

Reserve a port

Run this from the directory you want the reservation to belong to:

PORT=$(trop reserve) &&
  npm run dev -- --port "$PORT"

This Bash/Zsh example assumes an npm dev script that accepts --port. Use the returned number wherever your server expects a port argument.

Tags

Use tags when one worktree has multiple services:

WEB_PORT=$(trop reserve --tag web)
API_PORT=$(trop reserve --tag api)

Repeating a call with the same directory and tag returns the stored port. An untagged reservation is separate from every tagged reservation at that path.

Inspect and clean up

Command	Effect
trop list	Show the reservations in the database.
trop list --format json	Print the same records as JSON.
trop release --tag web	Release the web reservation for the current directory.
trop release	Release all tags, including the untagged reservation, at the current directory.
trop prune --dry-run	Preview removal of records whose paths no longer resolve to directories.
trop expire --days 30 --dry-run	Preview removal of records unused for 30 days.

Omit --dry-run to apply cleanup. Release leaves descendant directories alone unless you pass --recursive. Stopping a server does not release its reservation, and removing a reservation does not stop a server.

Service groups

For recurring multi-service workflows, define reservations in trop.yaml:

reservations:
  services:
    web:
      offset: 0
      env: WEB_PORT
    api:
      offset: 1
      env: API_PORT

This requests two consecutive ports, stored as the web and api tags for the directory containing the file. The group is reserved in one transaction: either both reservations succeed or neither does.

From that directory or a subdirectory:

trop autoreserve --format human

autoreserve searches upward for trop.yaml or .trop.yaml. Use trop reserve-group ./trop.yaml --format human to give an explicit path. Repeated calls reuse a complete, compatible group; a partial or incompatible stored group produces a conflict.

Use --format json for a tag-to-port mapping, --format dotenv for VAR=value lines, or --format export --shell bash for shell exports. These commands print output; they do not change the calling shell’s environment.

Each env name must be at most 255 bytes and match [A-Za-z_][A-Za-z0-9_]*. Without env, trop derives a name from an ASCII tag by converting letters to uppercase and replacing - with _. Other tags need an explicit valid mapping. Names must be unique ignoring ASCII case. These rules apply to every output format.

Upgrading from 0.1.0

Version 0.1.0 does not safely validate every generated variable name in export or dotenv output from autoreserve and reserve-group. Both 0.1.0 crates are yanked, but yanking does not remove installed binaries or update existing locked dependency resolutions. Upgrade the CLI explicitly:

cargo install trop-cli --version 0.2.0 --locked --force

Version 0.2.0 rejects invalid identifiers. See the GitHub security advisory for affected usage and remediation. Until upgraded, use human or JSON output, inspect the result, and set only trusted variables manually.

Database schema upgrades

The first writable launch against a schema-v1 database automatically migrates it to schema v2 in one durable transaction. trop checks all legacy rows before making changes. Duplicate keys or ports, empty legacy tags, invalid values, unexpected SQLite value types, and unsupported layouts stop the migration with recovery details; trop never silently chooses or discards a row.

A failed or interrupted migration leaves either the complete v1 database or the complete committed v2 database, never a hybrid. A read-only v1 database cannot be migrated, while read-only use works after a writable upgrade to v2.

The migration does not create a persistent backup or support a reverse migration. Older clients reject schema v2 without changing it. If you may need to downgrade, stop processes using trop and copy the complete data directory before the first launch of the newer client, then restore that copy if needed.