Command Reference

All portrm commands. The CLI binary is called ptrm.

Port Inspection

`ptrm scan`

List all listening ports with process details.

ptrm scan              # all ports
ptrm scan --json       # JSON output for scripting
ptrm scan --sort mem   # sort by memory usage

`ptrm <port>`

Inspect a specific port. Shows process name, PID, service type, memory, uptime, and safety classification.

ptrm 3000
ptrm 8080
ptrm 5432

`ptrm group`

View ports grouped by role (frontend, backend, database, cache, infra).

ptrm group
ptrm group --dev       # dev services only

Fix & Kill

`ptrm fix <port>`

Identify, check safety, and kill the process on a port. The primary command for resolving port conflicts.

ptrm fix 3000              # with confirmation prompt
ptrm fix 3000 -y           # skip confirmation
ptrm fix 3000 --run "npm run dev"  # kill + restart
ptrm fix 3000 8080 -y      # fix multiple ports
ptrm fix 3000 --force      # override safety checks

`ptrm kill <port>`

Direct kill without the detailed inspection output.

ptrm kill 3000
ptrm kill 3000 -y

Dev Stack Management

`ptrm init`

Generate a .ptrm.toml config file for your project. Scaffolds service definitions based on detected project structure.

ptrm init

`ptrm up`

Start all services defined in .ptrm.toml.

ptrm up                # start with conflict prompts
ptrm up -y             # auto-resolve conflicts
ptrm up frontend api   # start specific services

`ptrm down`

Stop all running services gracefully.

ptrm down
ptrm down frontend     # stop one service

`ptrm restart <service>`

Restart a specific service.

ptrm restart frontend
ptrm restart api

`ptrm use <profile>`

Switch to a different profile (dev, staging, production) defined in .ptrm.toml.

ptrm use staging
ptrm use production

`ptrm status`

Show live status of all configured services.

ptrm status

Monitoring & Diagnostics

`ptrm doctor`

Scan for zombie processes, idle servers, and port conflicts.

ptrm doctor            # report issues
ptrm doctor -y         # auto-fix safe issues

`ptrm watch <port>`

Monitor a port continuously. Auto-restarts the process if it crashes.

ptrm watch 3000

`ptrm preflight <ports>`

Verify ports are free before starting services. Reads from .ptrm.toml if no ports given.

ptrm preflight 3000 8080
ptrm preflight         # uses .ptrm.toml ports

`ptrm ci`

Run full CI check suite: config validation, registry check, preflight, and doctor. Exits with code 1 on failure.

ptrm ci
ptrm ci --json         # JSON output for CI pipelines

`ptrm history`

View action history and analytics.

ptrm history
ptrm history --stats   # aggregate statistics

`ptrm registry check`

Validate port assignments across all services and profiles in .ptrm.toml. Detects duplicate ports.

ptrm registry check

Other

`ptrm project`

Detect the current project type, suggest dev commands, and show default ports.

ptrm project

`ptrm log <port>`

Stream live logs from the process on a port.

ptrm log 3000

`ptrm ui`

Launch the interactive TUI (terminal UI) for browsing and managing ports.

ptrm ui

Global Flags

-y, --yes        Skip confirmation prompts
-f, --force      Override safety checks
--json           Output as JSON
--verbose        Show detailed debug output
--version        Show version
--help           Show help

Next: Real-world examples