CLI Reference

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

issue view <id>

View an issue by number

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)

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

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)

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

pr view <id>

View a pull request by number

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)

comment list <id>

List comments on an issue or PR

Options:

• -s,--since — Only comments updated at or after this ISO timestamp

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

comment edit <comment-id>

Edit a comment by ID, returns the updated comment

Options:

• -f,--body-file — Path to file containing the new body

comment view <comment-id>

View a comment by ID

label list

List all repo and org labels (populates cache)

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.

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

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

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.

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/.

pm assign <assignee> <id>

Assign an issue to a Forgejo user.

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.

pm prompt [name]

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

dev next [id]

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

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.

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.

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.

dev prompt [name]

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

qa next [id]

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

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.

qa checks <id>

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

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.

qa prompt [name]

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

wiki list

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

wiki view <slug>

View a wiki page by slug, with decoded content.

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

wiki revisions <slug>

List commit revisions for a wiki page.

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)

supervise next [id]

Run exactly one supervised tick: spawn a single agent container for 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.)
• --tick-timeout — Container timeout (seconds)
• --verbose — Print the raw SpawnResult JSON (full stderr) instead of the summary

supervise status

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

Options:

• --socket — Override the control socket path

supervise pause <role>

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

Options:

• --socket — Override the control socket path

supervise resume <role>

Resume scheduling for the given role.

Options:

• --socket — Override the control socket path

supervise kill <run-id>

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

Options:

• --socket — Override the control socket path

supervise reload

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

Options:

• --socket — Override the control socket path

telemetry emit

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

telemetry rebuild

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

telemetry compact

Fold per-branch shards whose newest event is older than --age-days (default 30) into .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

telemetry read <run-id>

Print the cmd, summary, event timeline, and (optionally) err transcript for a run. 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.