trop-cli

Command-line interface for trop, a lightweight port reservation management tool for concurrent development workflows.

Overview

trop helps prevent port collisions when running multiple development servers, test suites, or other services that need to bind to network ports. It provides idempotent, directory-based port reservations that work across multiple processes and concurrent agents.

Current Status

The CLI implements the core reservation workflow, configuration handling, group reservations, cleanup, assertions, migration, validation, completion generation, and inspection commands. The interface should still be considered preview-stage while real-world usage hardens edge cases.

Installation

Building from Source

# Clone the repository
git clone https://github.com/plx/trop.git
cd trop

# Build in release mode
cargo build --release

# The binary will be at: target/release/trop

Optionally, copy to a directory in your PATH:

cp target/release/trop ~/.local/bin/  # or /usr/local/bin/, etc.

From crates.io

cargo install trop-cli

Security upgrade from 0.1.0

Version 0.1.0 does not safely validate every environment-variable identifier generated by autoreserve and reserve-group for shell export and dotenv output. The fix is versioned as 0.2.0. Once that version is available from crates.io, upgrade explicitly:

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

Until upgraded, do not evaluate, source, or load export or dotenv output from those commands. Use --format human or --format json, inspect the result, and set only trusted variables manually. Yanking 0.1.0 does not remove an installed binary or update an existing lockfile.

Basic Usage

Currently available commands:

trop --version
trop --help
trop reserve
trop list
trop release --path /path/to/project

Common Usage

Simple Reservation

Reserve a port for the current directory:

port=$(trop reserve)
echo "Using port: $port"

Tagged Reservations

Reserve multiple ports for the same directory:

web_port=$(trop reserve --tag web)
api_port=$(trop reserve --tag api)
db_port=$(trop reserve --tag db)

Use in Build Scripts

Example justfile:

port := `trop reserve`

dev:
  npm run dev -- --port {{port}}

test:
  npm test -- --port {{port}}

Group Reservations

Reserve multiple ports at once from a trop.yaml file:

# Create trop.yaml with port definitions
trop reserve-group ./trop.yaml

# Or auto-discover trop.yaml
trop autoreserve

Configuration

trop will support hierarchical configuration:

1. Command-line arguments (highest priority)
2. Environment variables
3. trop.local.yaml (project-specific, not in source control)
4. trop.yaml (project config, checked into source control)
5. ~/.trop/config.yaml (user-level defaults)
6. Built-in defaults (lowest priority)

Example trop.yaml

project: my-app

ports:
  min: 5000
  max: 7000

excluded_ports:
  - 5432  # PostgreSQL default

reservations:
  base: 5000
  services:
    web:
      offset: 0
      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_]*. Without an explicit mapping, trop derives a name only from ASCII service tags by converting ASCII letters to uppercase and replacing - with _. Any other tag requires an explicit valid env name, and resolved names must be unique when compared without ASCII case.

See the implementation specification for complete configuration details.

Environment Variables

Key environment variables:

• TROP_DATA_DIR: Override data directory location (default: ~/.trop)
• TROP_LOG_MODE: Control logging verbosity (quiet, normal, verbose)
• TROP_PROJECT: Set project identifier
• TROP_DISABLE_AUTOINIT: Disable automatic database initialization

Commands

Core Operations

• trop reserve - Reserve a port for current directory
• trop release - Release a reservation
• trop list - List all active reservations
• trop reserve-group - Reserve multiple ports from config
• trop autoreserve - Auto-discover and reserve port group

Inspection

• trop port-info <port> - Show reservation info for a port
• trop assert-reservation - Check if reservation exists (exit code 0/1)
• trop assert-port <port> - Check if port is reserved (exit code 0/1)
• trop list-projects - List all active projects

Management

• trop prune - Remove reservations for deleted directories
• trop expire - Remove stale reservations
• trop autoclean - Combined prune and expire
• trop migrate - Move reservations between paths

Configuration

• trop init - Initialize data directory and config
• trop validate <config> - Validate a trop.yaml file
• trop scan - Scan for occupied ports
• trop exclude <port> - Add port to exclusion list

Utility

• trop show-data-dir - Print data directory path
• trop show-path - Print resolved path for reservation

Exit Codes

• 0 - Success
• 1 - Semantic error (e.g., assertion failed)
• 2 - Timeout (e.g., database lock)
• 3 - No data directory found
• 4+ - Other errors

Logging

All diagnostic output goes to stderr. Port numbers and structured output go to stdout, making the tool suitable for command substitution:

port=$(trop reserve)  # Only the port number goes to stdout

Control verbosity:

trop --quiet reserve      # Minimal output
trop reserve              # Normal output
trop --verbose reserve    # Detailed output

Or via environment:

export TROP_LOG_MODE=verbose
trop reserve

Use Cases

Multiple Worktrees

# Each worktree gets its own port automatically
cd ~/projects/myapp/feature-1
port=$(trop reserve)

cd ~/projects/myapp/feature-2
port=$(trop reserve)  # Different port!

Concurrent AI Agents

Multiple agents working on the same codebase in different directories automatically get non-conflicting ports.

Test Isolation

Each test suite run reserves its own ports, preventing interference between parallel test runs.

Limitations

• Single-user coordination only: Not designed for multi-user systems
• Coordination, not enforcement: Doesn't prevent other processes from using ports
• Localhost focused: Manages port numbers, not network interfaces

See the root README for more details.

Documentation

• Implementation Specification - Complete design
• Library API Documentation - Core library types
• Root README - Project overview and development setup

Generate API documentation:

cargo doc --open

Development

Running Tests

# Run all tests (unit + integration)
cargo test

# Run only CLI integration tests
cargo test --test cli

Development Mode

# Run without building first
cargo run -- --version

# With arguments
cargo run -- --help

Binary Details

• Binary name: trop
• Crate name: trop-cli
• Depends on: trop library crate

The CLI is a thin wrapper around the trop library, providing command-line parsing and output formatting.

License

trop-cli is dual-licensed under either:

• Apache License, Version 2.0, or
• MIT License,

at your option.

Support

This is an experimental project in active development. For issues or questions, see the main repository.

Warning

This is preview-stage software. The CLI interface and behavior may change as the tool gets more real-world use.