---
title: status
---

# status

Check the health of running services with an interactive table interface.

```sh
$ sysg status
```

When a supervisor is running, `sysg status` reads the supervisor's cached
snapshot instead of rebuilding live process state for every invocation. The
cache refresh interval and detail level are controlled by the top-level
`status` configuration block. Use `--live` when you need systemg to recompute a
fresh snapshot for that request.

## Interactive Mode

By default, `sysg status` displays an interactive table where you can:
- **Tab** or **↓** (Down arrow) - Move to the next service
- **Shift+Tab** or **↑** (Up arrow) - Move to the previous service
- **Enter** - Open the inspect view for the selected service
- **L** - Open a live log snapshot stream for the selected service
- **q** or **ESC** - Exit the status view

The selected row is highlighted with a white background for easy visibility.

> **Info:** Press **L** while a UNIT row is selected to open that unit's logs
> without leaving the status workflow. The shortcut runs
> `sysg logs -s <UNIT> -l 100 --stream 2`, giving you the latest 100 log lines
> and refreshing the snapshot every 2 seconds.

## Options

| Short | Long | Description |
|-------|------|-------------|
| `-c` | `--config` | Path to configuration file |
| `-s` | `--service` | Show specific service details |
| `-p` | `--project` | Filter by stable project id |
| `-` | `--all` | Show all services including orphaned state (services not in current config) |
| `-` | `--sys` | Opt into privileged system mode. Requires running as root |
| `-` | `--json` | Emit machine-readable JSON output instead of a table (disables interactive mode) |
| `-` | `--no-color` | Disable ANSI colors in output |
| `-` | `--live` | Force a fresh supervisor snapshot instead of reading the cached snapshot |
| `-` | `--stream` | Continuously refresh status at the provided interval (e.g., `5`, `1s`, `2m`) (disables interactive mode) |
| `-` | `--log-level` | Set verbosity (`debug`, `info`, `warn`, `error`) |

## Examples

### View all services

```sh
$ sysg status
```

```
SERVICE    STATUS    PID     UPTIME  CPU%  MEM%
postgres   running   14823   2h3m    0.1   2.3
redis      running   14824   2h3m    0.0   0.8
api        running   14826   2h3m    1.2   4.5
worker     running   14827   2h3m    0.3   3.1
```

### View specific service

```sh
$ sysg status --service api
```

```
Service: api
Status: running
PID: 14826
Uptime: 2h3m
CPU: 1.2%
Memory: 4.5%
Command: python app.py
```

### View a project

```sh
$ sysg status --project arbitration
```

Project filters use `project.id`, not the renameable project display name.

### Stream status updates

```sh
$ sysg status --stream 5
```

Stream mode polls the cached supervisor snapshot. It does not force a full
process scan on each redraw unless the supervisor is configured with a very
short `status.snapshot_interval_secs`.

### Force a fresh snapshot

```sh
$ sysg status --live
```

`--live` bypasses the cached read for this invocation and updates the cache with
the fresh result. With `status.snapshot_mode: summary`, the fresh snapshot still
uses the cheaper summary detail level; with `detailed`, it recomputes full
process and spawn-tree details.

## Performance

The default `status.snapshot_mode: summary` keeps status inexpensive for larger
systems by skipping process tree expansion, runtime command lookups, and per-pid
user/uptime lookups. Use `status.snapshot_mode: detailed` when you want richer
process and spawn-tree detail in status/inspect views.

## Output fields

- **SERVICE** - Service name from configuration
- **STATUS** - `running`, `stopped`, or `failed`
- **PID** - Process ID
- **UPTIME** - Time since service started
- **CPU%** - Current CPU usage
- **MEM%** - Current memory usage

## See also

- [`logs`](/how-it-works/commands/logs) - View service output
- [`restart`](/how-it-works/commands/restart) - Restart services
