CLI Command Reference

portctl commands and options cheat sheet.

Global Flags

Flag	Description
`-h, --help`	Print help information
`-V, --version`	Print version information
`--json`	Output response in structured JSON format

Commands

`portctl list`

Lists all assigned ports and real-time listening socket statuses.

portctl list [--json]

`portctl get [app]`

Resolves the deterministic port assigned to a project. If [app] is omitted, automatically detects from portctl.toml, package.json, Cargo.toml, etc.

portctl get [app] [--json]

`portctl init`

Initializes a declarative portctl.toml configuration file in the project root.

portctl init
portctl init --name my-service --port 4005 --domain service.example.com

`portctl run -- <command...>`

Executes any arbitrary command with $PORT injected into the environment.

portctl run -- npm run dev
portctl run -- uvicorn main:app --port $PORT

`portctl check [target]`

Probes socket status and retrieves process ownership (PID, process name, memory RSS).

portctl check           # Check current project
portctl check 3000      # Check specific port
portctl check my-app    # Check by service name
portctl check 3000 --json

`portctl assign <app>`

Registers an application with fixed or auto-incremented port allocations. If portctl.toml is present, automatically populates defaults.

portctl assign redis -f 6379 -s local --desc "Redis Cache Server"
portctl assign web-frontend -d frontend.example.com --json

portctl assign web-frontend -d frontend.example.com

### `portctl kill <target>`
Terminates processes occupying a socket using progressive SIGTERM -> SIGKILL escalation.

```bash
portctl kill 3000
portctl kill web-frontend
portctl kill 5432 --force   # Override protected infrastructure port guardrail

`portctl rename <old_name> <new_name>`

Renames a registered application while preserving its exact allocated port, ingress tunnel, and metadata.

portctl rename word-frequency-app wordradar
portctl rename legacy-api modern-api --json

`portctl delete <app> (alias: remove)`

Unregisters an application from the port registry and releases its port back to the allocation pool.

portctl delete old-service
portctl remove retired-worker --json

`portctl wait [target]`

Blocks script execution until a port or application service is listening and ready.

portctl wait 3000                       # Wait for port 3000 (TCP default)
portctl wait web-api -m http -t 15      # Wait for HTTP 2xx/3xx on web-api port within 15s
portctl wait --path /health --json      # Probe custom HTTP path with JSON output

`portctl expose <app>`

Automates Cloudflare Tunnel ingress configuration and daemon reload.

portctl expose my-app -d myapp.example.com

`portctl unexpose <app>`

Revokes Cloudflare Tunnel ingress routes and reloads the daemon.

portctl unexpose my-app

`portctl doctor`

Performs system health audit on permissions, lockfiles, and dangling ingress rules.

portctl doctor          # Audit only
portctl doctor --fix    # Automatically repair anomalies
portctl doctor --json   # Machine-readable report

`portctl env`

Generates .env variables or shell export statements.

portctl env -w          # Write PORT into .env or .env.local
portctl env -e          # Output 'export PORT=...'

`portctl completion <shell>`

Generates shell autocompletion script.

portctl completion zsh
portctl completion bash
portctl completion fish