Skip to content
trop

Usage

Install the CLI from Cargo:

Terminal window
cargo install trop-cli

Reserve a port for the current directory:

Terminal window
PORT=$(trop reserve)

Use tags when one worktree has multiple services:

Terminal window
WEB_PORT=$(trop reserve --tag web)
API_PORT=$(trop reserve --tag api)
DB_PORT=$(trop reserve --tag db)

Repeated calls with the same directory and tag return the same port. This keeps scripts stable across restarts without requiring each process to release a port before it exits.

Service Groups

Section titled “Service Groups”

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

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

Every reservation service must resolve to a portable export/dotenv identifier, regardless of the selected output format. Explicit env names must be at most 255 bytes and match [A-Za-z_][A-Za-z0-9_]*. When env is omitted, trop accepts ASCII service tags that become valid names after converting ASCII letters to uppercase and replacing - with _; all other tags require an explicit valid mapping. Resolved names must also be unique when compared without ASCII case.

Reserve the ports and inspect the resulting mapping by choosing one non-executable output format:

Terminal window
trop autoreserve --format human
# or
trop autoreserve --format json

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:

Terminal window
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

Section titled “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.