Reference for every `fjx` command, grouped by top-level subcommand.  Generated from the Cliffy command tree at version `0.4.0`.

Run `fjx <command> --help` for the live version at any time.

## Exit codes

| Code | Meaning                              |
| ---- | ------------------------------------ |
| 0    | Success                              |
| 1    | General error (network, API, parse)  |
| 2    | Usage error                          |
| 3    | Not found (e.g., no matching issues) |

<div style="margin-left: 1rem">

## `issue`

Issue operations

<div style="margin-left: 2rem">

### `issue list`

List issues, optionally filtered by label or assignee

**Options:**

- `-l,--label` — Filter by label (repeatable)
- `-s,--state` — Issue state: open|closed|all
- `-a,--assignee` — Filter by assignee username
</div>
<div style="margin-left: 2rem">

### `issue view <id>`

View an issue by number

</div>
<div style="margin-left: 2rem">

### `issue label <id>`

Add or remove labels on an issue, returns the updated issue

**Options:**

- `-A,--add` — Label to add (repeatable)
- `-r,--remove` — Label to remove (repeatable)
</div>
</div>
<div style="margin-left: 1rem">

## `pr`

Pull request operations

<div style="margin-left: 2rem">

### `pr push`

Push a branch to the remote using fjx credentials (FJX_TOKEN or FJX_USERNAME+FJX_PASSWORD). Required before `fjx pr create` when the branch has not yet been pushed.

**Options:**

- `-H,--head` — Branch to push
</div>
<div style="margin-left: 2rem">

### `pr create`

Create a pull request. fjx prepends an fjx-managed header (`Refs: #<N>`) above a `---` separator; --body-file is the agent-managed section below. Issue link is hard-required: --issue, or fall back to the current issue in cache.

**Options:**

- `-t,--title` — PR title
- `-H,--head` — Head branch
- `-b,--base` — Base branch
- `-i,--issue` — Issue this PR refers to. Defaults to current issue in cache.
- `-f,--body-file` — Path to file containing the agent-managed PR body (below the `---` separator)
</div>
<div style="margin-left: 2rem">

### `pr list`

List pull requests, optionally filtered by label or assignee

**Options:**

- `-l,--label` — Filter by label (repeatable)
- `-s,--state` — PR state: open|closed|all
- `-a,--assignee` — Filter by assignee username
</div>
<div style="margin-left: 2rem">

### `pr view <id>`

View a pull request by number

</div>
<div style="margin-left: 2rem">

### `pr label <id>`

Add or remove labels on a pull request, returns the updated PR

**Options:**

- `-A,--add` — Label to add (repeatable)
- `-r,--remove` — Label to remove (repeatable)
</div>
</div>
<div style="margin-left: 1rem">

## `comment`

Comment operations

<div style="margin-left: 2rem">

### `comment list <id>`

List comments on an issue or PR

**Options:**

- `-s,--since` — Only comments updated at or after this ISO timestamp
</div>
<div style="margin-left: 2rem">

### `comment create`

Create a comment on an issue or PR, returns the new comment with its ID

**Options:**

- `-i,--issue` — Issue number
- `-p,--pr` — PR number
- `-f,--body-file` — Path to file containing the comment body
</div>
<div style="margin-left: 2rem">

### `comment edit <comment-id>`

Edit a comment by ID, returns the updated comment

**Options:**

- `-f,--body-file` — Path to file containing the new body
</div>
<div style="margin-left: 2rem">

### `comment view <comment-id>`

View a comment by ID

</div>
</div>
<div style="margin-left: 1rem">

## `label`

Label operations

<div style="margin-left: 2rem">

### `label list`

List all repo and org labels (populates cache)

</div>
</div>
<div style="margin-left: 1rem">

## `pm`

PM workflow subcommands

<div style="margin-left: 2rem">

### `pm next [id]`

Run one PM cycle: sweep, plan, apply. Processes every open issue. Optional [id] pins the cycle to a single issue (matches `fjx dev next <id>` / `fjx qa next <id>`). Open issues with a merged PR are surfaced in `close_candidates`; use `pm close <N>` to finalize each one.

**Options:**

- `--plan-only` — Emit the plan as JSON without applying it
- `--brief-context-file` — Supply Context bullets for a brief refresh. Format: role=path/to/file.md. Each non-empty line of the file becomes one bullet. Repeatable.
</div>
<div style="margin-left: 2rem">

### `pm brief <id>`

Upsert the pm:brief comment on an issue by audience-scoped marker. Read-only when no --body-file provided.

**Options:**

- `-a,--audience` — Brief audience role
- `-f,--body-file` — Path to file containing the brief body
</div>
<div style="margin-left: 2rem">

### `pm ledger [id]`

Upsert the agent-pm:ledger comment. Defaults to current issue from cache if no ID provided. Read-only when no --body-file provided.

**Options:**

- `-f,--body-file` — Path to file containing the ledger body
</div>
<div style="margin-left: 2rem">

### `pm sweep`

Fetch issues and PRs updated since pm.last_swept_at, output candidates with their unprocessed comments. Sets pm.last_swept_at on success.

</div>
<div style="margin-left: 2rem">

### `pm close <id>`

Finalize an issue: set ledger Status: closed, append a closed Activity entry, close the issue on Forgejo, remove the issue's worktree if present. Emits notes verbatim so the operator can decide what to promote to wiki/.

</div>
<div style="margin-left: 2rem">

### `pm assign <assignee> <id>`

Assign an issue to a Forgejo user.

</div>
<div style="margin-left: 2rem">

### `pm release <id>`

Crash-recovery for an in-flight pm claim. Adds agent/blocked, reassigns to $FJX_OWNER, appends a crashed entry to the pm ledger, and clears the worktree pointer. Idempotent.

</div>
<div style="margin-left: 2rem">

### `pm prompt [name]`

Print a pm workflow prompt to stdout. Omit <name> to list available prompts. Names: bootstrap

</div>
</div>
<div style="margin-left: 1rem">

## `dev`

Developer workflow subcommands

<div style="margin-left: 2rem">

### `dev next [id]`

Start the next dev cycle: pick (or load <id>), claim, set up worktree, and emit the pm:brief. Must be run from the main checkout, not a worktree.

</div>
<div style="margin-left: 2rem">

### `dev done <id>`

Mark an issue's work ready for review: transition the issue to agent/review, assign the issue to agent-pm for routing, and assign the linked PR to $FJX_OWNER. Idempotent.

</div>
<div style="margin-left: 2rem">

### `dev ledger [id]`

Upsert the agent-dev:ledger comment. Defaults to current issue from cache if no ID provided. Read-only when no --body-file provided.

**Options:**

- `-f,--body-file` — Path to file containing the ledger body (agent-managed section only). Use '-' to read from stdin.
- `-s,--status` — Ledger status (required when writing). fjx computes checkpoint from current time.
</div>
<div style="margin-left: 2rem">

### `dev release <id>`

Crash-recovery for an in-flight dev claim. Adds agent/blocked, reassigns to $FJX_OWNER, appends a crashed entry to the dev ledger, and clears the worktree pointer. Idempotent.

</div>
<div style="margin-left: 2rem">

### `dev prompt [name]`

Print a dev workflow prompt to stdout. Omit <name> to list available prompts. Names: apply, bootstrap, investigate, propose, simple

</div>
</div>
<div style="margin-left: 1rem">

## `qa`

QA workflow subcommands

<div style="margin-left: 2rem">

### `qa next [id]`

Start the next QA cycle: pick (or load <id>), claim, set up worktree on the PR branch, and emit the pm:brief:qa. Must be run from the main checkout, not a worktree.

</div>
<div style="margin-left: 2rem">

### `qa ledger [id]`

Upsert the agent-qa:ledger comment. Defaults to current issue from cache if no ID provided. Read-only when no --body-file provided.

**Options:**

- `-f,--body-file` — Path to file containing the ledger body (agent-managed section only). Use '-' to read from stdin.
- `-s,--status` — Ledger status (required when writing). fjx computes checkpoint from current time.
</div>
<div style="margin-left: 2rem">

### `qa checks <id>`

List Forgejo Actions workflow runs for a PR's head commit

</div>
<div style="margin-left: 2rem">

### `qa release <id>`

Crash-recovery for an in-flight qa claim. Adds agent/blocked, reassigns to $FJX_OWNER, appends a crashed entry to the qa ledger, and clears the worktree pointer. Idempotent.

</div>
<div style="margin-left: 2rem">

### `qa prompt [name]`

Print a qa workflow prompt to stdout. Omit <name> to list available prompts. Names: bootstrap, default

</div>
</div>
<div style="margin-left: 1rem">

## `wiki`

Wiki page operations

<div style="margin-left: 2rem">

### `wiki list`

List wiki page metadata. Empty array if no wiki yet.

</div>
<div style="margin-left: 2rem">

### `wiki view <slug>`

View a wiki page by slug, with decoded content.

</div>
<div style="margin-left: 2rem">

### `wiki set <slug>`

Upsert a wiki page: create on 404, patch otherwise. Skips the write (returns action=unchanged) if content already matches and no --title rename is requested.

**Options:**

- `-f,--body-file` — Path to file containing the page content (markdown)
- `-t,--title` — Page title. Omit on edit to keep unchanged; required on create (defaults to slug).
- `-m,--message` — Commit message
</div>
<div style="margin-left: 2rem">

### `wiki revisions <slug>`

List commit revisions for a wiki page.

</div>
</div>
<div style="margin-left: 1rem">

## `init`

Scaffold slash-command wrappers in .agents/commands/fjx that delegate to `fjx <role>`. Idempotent. Use --force to overwrite differing files.

**Options:**

- `-f,--force` — Overwrite existing files that differ from the stub
- `-C,--root` — Project root to scaffold into (default: cwd)
</div>
<div style="margin-left: 1rem">

## `supervise`

Long-running supervisor daemon and its control surface.

<div style="margin-left: 2rem">

### `supervise start <project-dirs...>`

Run the supervisor daemon. Drives agent ticks across the listed project dirs on adaptive cadences via per-cycle Docker containers. SIGTERM drains in-flight ticks then exits. SIGHUP reloads each project's fjx.json without restarting.

**Options:**

- `--no-spawn` — Disable container spawning and scheduling (runtime adapters only)
- `--base-cadence` — Base interval between ticks per role (seconds)
- `--max-cadence` — Maximum interval after consecutive no-ops (seconds)
- `--tick-timeout` — Per-tick container timeout (seconds)
- `--socket` — Override the control socket path (default: $FJX_SUPERVISE_SOCK or $XDG_RUNTIME_DIR/fjx-supervise-$USER.sock)
</div>
<div style="margin-left: 2rem">

### `supervise next [id]`

Run exactly one supervised tick: spawn a single agent container for <role> against the project at --project (default: cwd), wait for it to exit, print the result. Optional [id] pins the agent to that issue (`fjx <role> next <id>`) instead of letting the planner pick. No daemon, no cadence, no control socket — useful for validating container/image changes against a known issue.

**Options:**

- `--role` — Role to spawn (pm | dev | qa | …)
- `--project` — Project directory
- `--image` — Override the image (default: project's fjx.json images.<role>)
- `--tick-timeout` — Container timeout (seconds)
- `--verbose` — Print the raw SpawnResult JSON (full stderr) instead of the summary
</div>
<div style="margin-left: 2rem">

### `supervise status`

List in-flight ticks (project, role, run-id, start time).

**Options:**

- `--socket` — Override the control socket path
</div>
<div style="margin-left: 2rem">

### `supervise pause <role>`

Halt scheduling for the given role. In-flight ticks continue.

**Options:**

- `--socket` — Override the control socket path
</div>
<div style="margin-left: 2rem">

### `supervise resume <role>`

Resume scheduling for the given role.

**Options:**

- `--socket` — Override the control socket path
</div>
<div style="margin-left: 2rem">

### `supervise kill <run-id>`

Abort the in-flight tick with the given run-id.

**Options:**

- `--socket` — Override the control socket path
</div>
<div style="margin-left: 2rem">

### `supervise reload`

Reload each project's fjx.json without restarting the daemon.

**Options:**

- `--socket` — Override the control socket path
</div>
</div>
<div style="margin-left: 1rem">

## `telemetry`

Telemetry ingest, index, and compaction

<div style="margin-left: 2rem">

### `telemetry emit`

Read stdin line-by-line. Valid fjx event lines (JSON with ts/type/fjx_id) are appended to ./telemetry/<branch>.jsonl; all other lines pass through to stdout unchanged.

</div>
<div style="margin-left: 2rem">

### `telemetry rebuild`

Drop and regenerate ./fjx.sqlite from every ./telemetry/*.jsonl shard. Safe to re-run; the JSONL files are the source of truth.

</div>
<div style="margin-left: 2rem">

### `telemetry compact`

Fold per-branch shards whose newest event is older than --age-days (default 30) into <year-month>.jsonl archives. Removes the absorbed shards and stages the changes; the operator runs git commit themselves.

**Options:**

- `--age-days` — Compact shards whose newest event is older than this many days
- `--no-stage` — Skip running `git add` after rewriting files
</div>
<div style="margin-left: 2rem">

### `telemetry read <run-id>`

Print the cmd, summary, event timeline, and (optionally) err transcript for a run. <run-id> may be the 8-char prefix or a full UUID.

**Options:**

- `--err` — Also print the full agent transcript (stderr).
- `--tail` — With --err: print only the last N lines of the transcript.
</div>
</div>