# fleetctl reference

`fleetctl` is the local controller's command-line client. It is bundled at `FleetConsole.app/Contents/Resources/bin/fleetctl`; it is not necessarily on PATH. Start with the actual installed app location:

```bash
"/Applications/FleetConsole.app/Contents/Resources/bin/fleetctl" --help
"/Applications/FleetConsole.app/Contents/Resources/bin/fleetctl" doctor
```

Substitute the bundle path if needed. `doctor` checks installation, connectivity and local state; it does not install or restart the controller.

## Inspection syntax

| Command | Scope |
| --- | --- |
| `list [--all] [--json]` | Services, unmanaged work and attention; `--all` includes stopped/crashed records |
| `show <id\|name> [--json]` | One full service, including declared/listening ports and health evidence |
| `agents [--json]` | Recorded work grouped by agent |
| `events [<id\|name>] [--limit 50] [--json] [--offline]` | Global or one-service history; offline is historical, not live |
| `logs <id\|name> [--err] [--bytes 64000]` | Captured stdout or stderr tail |
| `ping` | Controller identity and timing diagnostics |
| `doctor` | Installation and controller diagnostics |

`list`, `show`, `agents`, `events` and `inbox` accept `--json`. Logs, ping and doctor produce human-readable diagnostics. Preserve output privately when commands or paths expose personal work.

## Actions and authority

`launch --name <n> --owner <agent> --purpose <why> [options] -- <command> [args…]` starts a new controller-managed process. Required metadata identifies the request; it does not grant an agent permission to create arbitrary work. `--cwd` chooses the project directory; `--lease` supplies a duration, defaulting to one hour. Durations include `30s`, `15m`, `2h`, `1d` or seconds.

`renew <id|name> [--lease 30m]` extends a lease within configured limits. `pause`, `resume`, `restart`, `stop` and `kill` control only controller-launched services after identity verification. Pause retains ports and memory. Restart replays recorded argv. Kill has no grace period.

`claim` records an already-running process with an owner, purpose and lease but grants no signalling authority. Claimed and unmanaged work cannot be controlled through these service actions.

## Messages and housekeeping

`notify`, `inbox` and `reply` implement operator messages. `reconcile`, `claim`, `ignore`, `prune` and `config --reload` can change observations, records or configuration; they are not interchangeable with read-only inspection. A shell opened inside the app remains unsupervised unless it explicitly launches work through `fleetctl`.

Registry/configuration live under `~/Library/Application Support/FleetConsole`; logs under `~/Library/Logs/FleetConsole`. The controller uses an owner-only Unix socket. See the [maintained CLI documentation](https://github.com/janestreetshiller/fleet-console/blob/87c38aff663db2e0c70e90eea5c8781ceb32a1e4/docs/CLI.md) for detailed launch and housekeeping options.