# systemg

> systemg is an agent-friendly general process composer: a single `sysg` binary that
> starts, supervises, restarts, inspects, and logs local service graphs defined
> in YAML. It is useful for development environments, local stacks, CI jobs,
> cron-style units, and agent-managed workflows.

Current release: `0.51.0`

Primary links:

- Documentation: https://sysg.dev
- Quickstart: https://sysg.dev/quickstart
- Installation: https://sysg.dev/installation
- Commands: https://sysg.dev/how-it-works/commands
- Logs command: https://sysg.dev/how-it-works/commands/logs
- Status command: https://sysg.dev/how-it-works/commands/status
- Configuration: https://sysg.dev/how-it-works/configuration
- Validate command: https://sysg.dev/how-it-works/commands/validate
- Claude Code integration: https://sysg.dev/integrations/claude-code
- Repository: https://github.com/ra0x3/systemg

## Agent-Friendly Usage

Use `--plain` for scripts, pipes, SSH sessions, and coding agents:

```sh
sysg --plain status
sysg --plain status --format json
sysg --plain inspect -s api --format json
sysg --plain logs -s api --format json
```

`--plain` sets `SYSTEMG_AGENT=1` for the current process. Agent mode is also
enabled when `SYSTEMG_AGENT` or `NO_COLOR` is set. In agent mode, systemg avoids
color, banners, paging, truncation, and accidental log-following where possible.

## Commands LLMs Should Prefer

- `sysg validate -c <file>`: check a manifest before running it. Exits `0` when
  valid, `1` otherwise. Add `--format json` for structured diagnostics with the
  line, column, category, message, and suggested fix. Run this after writing or
  editing any config.
- `sysg --plain status`: human-readable, non-interactive status with full unit
  names.
- `sysg status --format json`: structured supervisor status for parsing.
- `sysg inspect -s <unit> --format json`: structured details for one service or
  cron unit.
- `sysg logs -s <unit> --format json`: JSON-lines logs with `{ts, stream,
  service, line}` fields.
- `sysg logs -s <unit> --raw`: application log lines without systemg timestamp
  or stream prefixes.
- `sysg logs -s <unit> --grep ERROR --since 2h`: filtered one-shot log query.
- `sysg logs --path` or `sysg logs -s <unit> --path --all`: locate active and
  rotated log files for external tooling.

## Log Behavior

As of `0.50.0`, `sysg logs` is safe for non-interactive callers by default. It
follows logs only when stdout is an interactive terminal and agent mode is not
enabled. In pipes, files, SSH commands, and agent sessions, it prints a one-shot
snapshot and exits. Use `--follow` only when a long-running tail is intended;
use `--no-follow` to force a one-shot snapshot on a terminal.

Useful log options:

- `--format json`: clean JSON-lines output for parsing.
- `--raw`: only the application's original line.
- `--strip-ansi`: remove terminal color and escape sequences.
- `--no-strip-ansi`: preserve recorded ANSI escapes.
- `--since`, `--until`: time-window logs by systemg capture timestamp.
- `--grep`: regex filter.
- `--all`: read active plus rotated history, oldest to newest.

## Install

```sh
curl --proto '=https' --tlsv1.2 -fsSL https://sh.sysg.dev/ | sh
```
