nc (netcat) Command Reference: Flags, Usage & CI Examples

nc (netcat) reads and writes data across TCP and UDP connections.

nc opens, listens on, and probes network connections. In CI its most common job is a TCP port check that waits for a service container or sidecar to accept connections.

Common flags and usage

• -z: scan without sending data (port check)
• -v: verbose; report success or refusal
• -w <secs>: connection timeout
• -l -p <port>: listen on a port
• -u: use UDP instead of TCP
• nc <host> <port>: open a connection

Example

until nc -z -w2 localhost 5432; do
  echo "waiting for port 5432..."; sleep 1
done

In CI

nc -z -w2 host port is a protocol-agnostic readiness gate that works for any TCP service, not just databases. Note BSD and GNU netcat differ in flags, and busybox nc may lack -z, so a /dev/tcp bash redirect is a portable fallback.

Key takeaways

• nc -z probes a TCP port without sending data.
• It is a protocol-agnostic wait-for-port gate in CI.
• netcat variants differ; check that -z exists on your image.

Related guides