---
title: logs
---

# logs

View stored output from managed services.

```sh
$ sysg logs
```

> **Info:** From the interactive `sysg status` table, select a UNIT with
> Tab/arrow navigation and press **L** to jump straight into that unit's logs.
> The status shortcut runs `sysg logs -s <UNIT> -l 100 --stream 2`, which shows
> the latest 100 lines and refreshes the snapshot every 2 seconds.

## Options

| Short | Long | Description |
|-------|------|-------------|
| `-c` | `--config` | Path to configuration file |
| `-` | `--purge` | Reset log files instead of displaying them |
| `-s` | `--service` | The name of the service whose logs should be displayed (optional) |
| `-p` | `--project` | Filter logs by stable project id |
| `-l` | `--lines` | Number of lines to show (default: 50) |
| `-k` | `--kind` | Kind of logs to show: stdout, stderr, or supervisor. Omit this flag to show stdout+stderr together |
| `-` | `--stream` | Continuously refresh the latest log snapshot at the provided interval (e.g., `5`, `1s`, `2m`) |
| `-` | `--sys` | Opt into privileged system mode. Requires running as root |
| `-` | `--log-level` | Set verbosity (`debug`, `info`, `warn`, `error`) |

## Examples

### View recent logs from all services

```sh
$ sysg logs
```

### View logs from specific service

```sh
$ sysg logs --service api
```

To disambiguate a service in a multi-project supervisor, provide the stable
project id:

```sh
$ sysg logs --project arbitration --service api
```

> **Info:** By default, `sysg logs` shows a stacked stdout+stderr stream in
> capture order. systemg adds its own UTC capture timestamp and stream label to
> service output as it is written, then reads the combined service log for the
> default view. Use `--kind stdout` or `--kind stderr` when you need a single
> stream only.

### Purge logs for a specific service

```sh
$ sysg logs --service api --purge
```

This truncates `api`'s current `stdout` and `stderr` log files in place and does not print logs.

### Purge logs for all services

```sh
$ sysg logs --purge
```

This truncates all service log files, plus `supervisor.log`, in place and does not print logs.

### View stderr logs

```sh
$ sysg logs --service api --kind stderr
```

### View supervisor logs

```sh
$ sysg logs --kind supervisor
```

### Show more history

```sh
$ sysg logs --service api --lines 200
```

### Stream snapshots

```sh
$ sysg logs --service api --lines 200 --stream 2
```

In stream mode, each refresh prints a new snapshot of the latest `--lines` entries.

## Log files

Logs are stored in `~/.local/share/systemg/logs/`:
- `{service}.log` - Canonical stdout+stderr stream in capture order
- `{service}_stdout.log` / `{service}_stderr.log` - Legacy split-stream files from older systemg versions, still read as a fallback when no canonical log exists

Each captured service line is stored with a systemg capture timestamp and stream
label:

```text
2026-05-14T02:05:13.470911Z stderr Compiling tungstenite v0.28.0
2026-05-14T02:05:13.471020Z stdout request completed status=200
```

## Performance model

For the default `file` logging sink, systemg captures each service's stdout and stderr through pipes and writes both streams through one per-service writer into `{service}.log`. On Linux and macOS, the default `sysg logs` view tails that file directly with `tail -F` in follow mode. `--kind stdout` and `--kind stderr` filter recent captured lines by the stored stream label. The command itself is lightweight; the continuous cost comes from the capture threads, one writer thread, and one append-only file write path per service.

For high-output production workloads, configure `logs.sink: none` globally or per service to discard service output and avoid systemg log-writer threads, pipe backpressure from log capture, and file growth.

## See also

- [`status`](/how-it-works/commands/status) - Check service health
- [`inspect`](/how-it-works/commands/inspect) - View detailed metrics
