run

portcheck run

Run a command on a free port (sets $PORT)

Synopsis

Run a command on a usable port, passing it in $PORT and replacing {port} in the command's arguments.

With --port, that port is used if it's free. If it's taken, run explains who holds it and stops, unless --next picks the next free port or --kill stops the holder (with the same confirmation and safety guards as 'portcheck kill'). Without --port, the first free port in --range is used.

The command runs in the foreground with your terminal; Ctrl+C reaches it directly. portcheck exits with the command's exit status. portcheck's own messages go to stderr.

portcheck run [flags] [--] <command> [args...]

Examples

  portcheck run --port 3000 -- npm start
  portcheck run --port 3000 --next -- npm run dev
  portcheck run --port 8080 --kill --yes -- ./server
  portcheck run -- python3 -m http.server {port}
  portcheck run --port 5173 --wait -- npx vite --port {port}

Options

      --env string              environment variable that receives the port (default "PORT")
  -f, --force                   with --kill: kill immediately without a graceful request
      --grace duration          with --kill: how long to wait for a graceful exit (default 5s)
  -h, --help                    help for run
      --kill                    if --port is taken, stop the process holding it (asks first)
      --next                    if --port is taken, use the next free port above it
  -p, --port string             port number, or a name from .portcheck.yaml (default: first free port in --range)
  -q, --quiet                   don't print portcheck's own messages
      --range string            ports to choose from when --port is not given (default "3000-9999")
      --wait                    report when the command starts accepting connections
      --wait-timeout duration   with --wait: how long to wait (default 1m0s)
  -y, --yes                     with --kill: don't ask for confirmation

Options inherited from parent commands

      --json                shorthand for --output json
      --log-format string   log format: text or json (default "text")
      --no-color            disable colors (also honors NO_COLOR)
  -o, --output string       output format: table, plain, csv, json (default: table on a terminal, plain otherwise)
  -v, --verbose             log diagnostic details to stderr

SEE ALSO

• portcheck - See what's using your ports, find free ones, and free them up