Search across all documentation pages
Node gives you a comfortable set of abstractions - process, require, streams, an event loop - that mostly let you forget the operating system underneath. The Linux command line is where that forgetting stops paying off. It's the layer where a Node process is just one more entry in the kernel's process table, a socket is just a file descriptor, and "my API stopped responding" resolves into concrete, checkable facts instead of guesses.
This page is not a tour of curl, jq, or top - CLI Basics for Node and Process Inspection already cover those commands hands-on. This page is the model underneath them: why the shell matters to a Node engineer specifically, and how the primitives it exposes - processes, signals, file descriptors - line up with concepts you already reason about in application code.
EADDRINUSE or file-descriptor exhaustion, and verifying a deploy or restart actually took effect at the process level.Every Node process you run - node server.js, a pm2 worker, a container's entrypoint - is registered with the Linux kernel exactly like any other program: it gets a process ID, an entry in the process table, a set of open file descriptors, and a way to receive signals from the OS or from other processes. Nothing about "Node-ness" is visible to the kernel at that level. The kernel doesn't know or care that your process happens to be running an event loop; it just knows a PID exists, how much memory it maps, and which sockets and files it has open.
The shell is the tool that lets you ask the kernel about that reality directly, instead of asking your application to report on itself. A useful way to picture it: your app's /health endpoint and its console.log output are like a company's press releases - accurate when everything is working, but written by the same entity you're trying to verify. The shell is closer to pulling the building's utility meters directly: ps and top read straight from the kernel's process accounting, lsof reads straight from the kernel's file-descriptor table, and neither one depends on your application code being healthy enough to answer a request.
That distinction matters because Node's own process model is a thin, friendly wrapper around exactly these primitives. process.pid is the same PID ps would show you. process.stdout and process.stderr are the same standard streams a shell redirects with > and 2>. An exit code your Node process returns from process.exit(1) is the same number echo $? reads back in the shell right after.
node server.js &
echo $! # the PID the shell just handed to Node
ps -p $! # the same PID, seen from the kernel's sideThe clearest place this pairing shows up is signals. When you run kill -15 <pid> (or Kubernetes sends the equivalent during a pod termination), the kernel delivers SIGTERM to your Node process, and your application code sees it as an ordinary event:
process.on('SIGTERM', async () => {
server.close(); // stop accepting new connections
await drainConnectionPool();
process.exit(0);
});There is nothing Node-specific about this handshake - it's the standard POSIX termination signal, and Node just gives you an event-emitter-shaped way to listen for it. The reason this matters operationally is that kill -9 (SIGKILL) skips this entirely: the kernel terminates the process immediately, with no chance for your handler to run, which is why a graceful shutdown depends on whoever is supervising the process (systemd, Kubernetes, pm2) sending SIGTERM first and waiting before escalating.
Sockets follow the same pattern. When your Express or Fastify server calls .listen(3000), Node asks the kernel to bind a file descriptor to that port; lsof -i :3000 or ss -tlnp reads that same kernel table back, which is why they can definitively answer "is anything actually listening on 3000, and what PID owns it" even when the app itself is unresponsive to HTTP requests. This is also where file descriptor limits become visible: a Node process that leaks open sockets or file handles will show a climbing count in lsof -p <pid> | wc -l long before it shows up as an application-level symptom, because the OS enforces a hard per-process ceiling (ulimit -n) regardless of what your code believes about its own connection pool.
top and htop read the kernel's memory accounting directly, which is why they show RSS (resident set size - actual physical memory the process occupies) rather than V8's heapUsed. Those two numbers measure different things: heapUsed is what V8's garbage collector tracks inside its own managed heap, while RSS includes that heap plus buffers, native addon memory, and everything else mapped into the process. A Node process can have a small, healthy heapUsed and still be the reason a host runs out of memory, and only the shell-level view catches that.
Containers add a layer between what the shell shows you and what's actually true on the host, and this is the single most common source of confusion for engineers moving from bare-metal or VM debugging into Kubernetes. Inside a container, top shows processes through that container's PID namespace - your Node process might report as PID 1, with no other processes visible - which can look like a healthy, isolated system even when the host is under severe memory pressure from other pods on the same node. kubectl top pod or kubectl exec ... -- cat /sys/fs/cgroup/memory.current reads the cgroup limit that actually governs OOM behavior, and it's frequently a very different number from what free -h reports inside the container. Getting comfortable with that gap - container view versus cgroup limit versus host reality - is now a core part of CLI fluency, not an edge case.
There's also a real difference between reaching for the shell directly and reaching for the tooling built on top of it. Both answer the same underlying question - "what is my Node process actually doing" - but at different scales and with different guarantees:
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
Direct shell inspection (ps, top, lsof, ss) | Ground truth, no dependency on app health, works even when HTTP is unresponsive | Point-in-time only; no history; requires host/container access | Live incident triage, confirming a specific claim right now |
Structured log queries (jq over JSON logs) | Correlates events by requestId/traceId; searchable after the fact | Only as good as what the app chose to log | Reconstructing a request's path through the system |
| APM / metrics dashboards | Trends over time, alerting, cross-service correlation | Aggregated - can hide a single misbehaving process; another system to trust | Capacity planning, spotting gradual regressions |
None of these replaces the others. A dashboard tells you error rate is climbing; the shell tells you which specific PID is consuming the memory driving it; structured logs tell you which requests were involved. Treating shell fluency as a baseline skill - not a "last resort when the dashboard is down" skill - is what makes the other two tools faster to use correctly, because you already know what a sane process should look like at the OS level.
console.log and app metrics are enough; I don't need the shell." They report what your code believes about itself - the shell reports what the kernel actually observes, and the two diverge exactly when you most need accurate information (a hung event loop, a leaked socket).top/htop memory numbers and heapUsed are the same thing." RSS (what the shell shows) includes the V8 heap plus buffers, native addon memory, and everything else mapped into the process; heapUsed is only the managed-heap slice V8's GC tracks.kill and kill -9 do basically the same thing, just faster." SIGTERM (kill -15, the default) gives your process a chance to run shutdown handlers; SIGKILL (kill -9) terminates it immediately with no chance to drain connections or close handles.top shows me the same thing the host sees." The container's PID namespace isolates what processes are visible and what resource totals are reported; the cgroup limit governing actual OOM behavior is a separate number you have to check explicitly.Because every Node process runs as an ordinary Linux process underneath - the kernel doesn't know or care that it's running JavaScript. Reasoning about PIDs, file descriptors, and signals lets you verify what your application claims about itself instead of trusting logs and metrics that depend on the app already being healthy.
They're the same event from two sides. kill -15 <pid> (or an orchestrator's equivalent termination request) asks the kernel to deliver the SIGTERM signal to that process; Node exposes that delivery as an ordinary event your code can listen for and react to before exiting.
They measure different scopes. heapUsed is only the portion of memory V8's garbage collector manages inside its own heap; RSS (what top reports) includes that heap plus buffers, native addon allocations, and anything else the OS has mapped into the process - it's possible for RSS to grow steadily while heapUsed looks stable.
It reads the kernel's file-descriptor table directly to show exactly which process (if any) already owns that port, which is the fastest way to resolve EADDRINUSE - you get a real PID to inspect or kill rather than guessing which of several running processes is the culprit.
Rarely as a first move. SIGKILL gives the process no chance to run its shutdown handlers, so in-flight requests get dropped and connections aren't drained cleanly. The normal sequence is SIGTERM first, then SIGKILL only after a grace period if the process hasn't exited.
Because top inside a container reports through that container's PID namespace, which can look self-contained and healthy even as the host's cgroup accounting - the number that actually governs OOM behavior - is close to its limit. Checking the cgroup limit directly (or kubectl top pod) is necessary to see the number that matters.
It's the kernel's handle for anything your process has open - a listening socket, an open file, a pipe. Node abstracts these behind streams and socket objects, but the OS enforces a real per-process limit (ulimit -n) on how many can be open at once, independent of what your application code believes its connection pool size is.
Plain-text log grepping doesn't scale well against structured logs, so tools like jq become the shell-side counterpart to a logger like Pino - filtering by level, requestId, or traceId the same way grep once filtered plain text, but without breaking on multi-line JSON.
No - they answer different questions at different scales. Dashboards show trends and cross-service correlation over time; the shell shows exact, current, ground-truth state for one host or process. Effective troubleshooting moves between both.
That endpoint depends on the application's event loop being free enough to respond - which is precisely what's in question during a stall or overload incident. Shell-level tools read kernel state directly and can answer "is the process even alive and listening" without needing the app to cooperate.
Process managers, cluster mode, and worker-thread-backed processes (worker_threads spins up OS threads within one process, but child_process.fork() spins up entirely separate PIDs) can multiply the visible process count. Reading the command-line arguments column distinguishes the primary API process from workers, cron jobs, or leftover processes from a previous deploy.
curl, jq, and ss recipes built on this modeltop, htop, and lsof walkthroughs for port conflicts and resource pressureSIGTERM/graceful-shutdown handshake this page introducesStack versions: This page was written for Node.js 24 LTS running on standard Linux distributions (systemd-managed hosts and container runtimes alike).
Reviewed by Chris St. John·Last updated Jul 15, 2026