---
name: process-compose
description: Inspect a running process-compose project read-only. Use when the user asks what services/processes are running, whether a service is up or healthy, what state a process is in, or to read a service's recent log output — or mentions process-compose (pc) by name.
---

# Inspecting process-compose

The `process-compose` CLI is a thin **client**. It does not read your config or
processes directly — it queries a process-compose **server** that is already
running (the one started by `process-compose up`). Every command below talks to
that server over TCP, default `localhost:8080`.

This skill is **read-only**: never start, stop, restart, or scale processes.

## Connecting

- Default target is `localhost:8080`. If a project runs on another port, pass
  `-p PORT` (or set `PC_PORT_NUM`); the port is whatever that project's
  `process-compose.yaml` / launch command set.
- A "connection refused" error means **no server is running on that port**, not
  a bad command. Report that the project isn't up rather than retrying variants.
- `pc` is a fish abbreviation for `process-compose` and exists only in an
  interactive fish shell. In scripts and Bash calls use the full `process-compose`.

## Read commands

List every process with its status (one line each):

```
process-compose process list -o wide
```

Add `-o json` when you need to parse fields (status, health, pid, restarts, exit
code) rather than display them.

Full state of one process:

```
process-compose process get NAME -o json
```

Recent log lines for a process (tail the last N — adjust the number to the need):

```
process-compose process logs NAME -n 100
```

Multiple processes: comma-separate them (`proc1,proc2`). A whole namespace:
`-N NAMESPACE`.

Whole-project state (is everything ready):

```
process-compose project state
```

## Never do

- **No TUI.** Bare `process-compose`, `up`, and `attach` launch the interactive
  full-screen TUI and hang a non-interactive shell. Always use a subcommand.
- **No `-f` / `--follow`** on `logs` — it streams forever and blocks. Use `-n` to
  pull a finite tail instead.
- **No mutations** — `start`, `stop`, `restart`, `scale`, `down` are out of scope
  for this skill.