---
title: "Observe terminal guide"
description: "Use Hew v0.9.3's terminal observer: connect by address or discover a process, navigate seven views, filter actors and inspect events."
source: "https://hew.sh/docs/observe/terminal"
---

# Observe in the terminal

Inspect a running actor system from your terminal with hew observe.

Install the [Hew v0.9.3 SDK](/docs/getting-started). Its terminal observer is the `hew observe` subcommand. Keep the observer and program compiler from the same SDK release.

## Connect to a program

Start the program, then attach from another terminal

```bash
hew build my_program.hew -o my_program
HEW_OBSERVE=hot HEW_PPROF=127.0.0.1:6060 ./my_program
# In another terminal:
hew observe --addr 127.0.0.1:6060
```

Leave the program running. To explore without a program, use `hew observe --demo`. The screenshots below show that sample-data mode.

![Hew terminal observer showing scheduler, message-rate and memory panels in demo mode](/images/observe/terminal-overview.png)

Overview shows activity, workers, memory and the busiest actors. The screenshot was captured from the Observe v1 demo included with Hew 0.6.2; the seven-view workflow remains current in v0.9.3.

### Discover a local process on Unix

Use a per-user profiler socket

```bash
hew run my_program.hew --profile
# In another terminal:
hew observe
# If several programs are running:
hew observe --list
hew observe --pid 12345
```

Choose the actual PID reported by `--list`. With no profiler available, the observer waits and rescans. Use `--addr` for TCP endpoints and on platforms without Unix-socket discovery.

## Navigate the seven views

Use Tab and Shift+Tab to change views. Press ? for help, r to refresh, and q or Ctrl+C to exit.

![Terminal Actors view with actor state, mailbox and processing counters](/images/observe/terminal-actors.png)

Actors: use Up/Down to select, s to change sorting and / to enter a filter.

-   **Overview:** check activity and memory before narrowing the investigation.
-   **Actors:** compare mailbox depth and processing time; Enter accepts a typed filter and Escape clears it.
-   **Supervisors:** select a role to inspect its current incarnation and mailbox data; Enter focuses that role's events.
-   **Crashes:** move through reported failures with Up/Down.
-   **Cluster:** inspect this producer's membership, routes and connections.
-   **Messages:** p or Space pauses, f filters the selected actor and c clears the filter.
-   **Timeline:** Left/Right pans, +/- zooms, n follows the latest events and p or Space pauses.

See the other five terminal screens

![Terminal supervisors view with sample actor data](/images/observe/terminal-supervisors.png)

Supervisors in the Observe v1 terminal interface.

![Terminal crashes view with sample actor data](/images/observe/terminal-crashes.png)

Crashes in the Observe v1 terminal interface.

![Terminal cluster view with sample actor data](/images/observe/terminal-cluster.png)

Cluster in the Observe v1 terminal interface.

![Terminal messages view with sample actor data](/images/observe/terminal-messages.png)

Messages in the Observe v1 terminal interface.

![Terminal timeline view with sample actor data](/images/observe/terminal-timeline.png)

Timeline in the Observe v1 terminal interface.

## Inspect multiple nodes

Add TCP producers

```bash
hew observe --addr 127.0.0.1:6060 --node 127.0.0.1:6061
# --node can be repeated; use [ and ] to change the active node.
# Optional polling interval:
hew observe --addr 127.0.0.1:6060 --refresh-ms 2000
```

## If it cannot connect

Check that the process is still running and the port matches. Try `curl --fail http://127.0.0.1:6060/api/metrics`. For discovery, run `hew observe --list`. The observer needs an interactive terminal; use the [HTTP API](/docs/profiler#json-api) in scripts. Keep profiler ports on loopback or a trusted network because they expose runtime details without login.

For `.hewobs` recording and offline replay, use the [desktop app](/docs/observe#record). Read the [full terminal manual](/observe/manual/manual.html#terminal-observer) or [download the PDF](/observe/manual/manual.pdf).