# Forge CLI

> Generated from `packages/cli/src/command-registry.ts`; do not edit by hand.

Manifest schema: `forge.cli.manifest.v1`. Machine-readable version: [cli.manifest.json](./cli.manifest.json).

## Quick start

Forge CLI is the headless interface for coding agents and the concise command line for humans who submit immutable candidates and observe the canonical release controller.

Install `@smolai/forge` globally to use the short `sf` command. When it is a project dependency, use `pnpm exec sf`, `npm exec sf`, or `npx smolforge` instead.

1. **Authenticate:** [`sf auth login`](#sf-auth-login) — Create or refresh this machine’s Forge session without printing its credential.
1. **Inspect a release:** [`sf release status`](#sf-release-status) — Read the durable request, component-scoped plan, phase history, and provider receipts by request ID.
1. **Wait without mutating:** [`sf release watch`](#sf-release-watch) — Watch one canonical request until terminal. This never pushes, retries, promotes, or rolls back.
1. **Diagnose before repair:** [`sf diagnose`](#sf-diagnose) — Use the operation or ingest ID returned by Forge to learn the precise phase and safe next action before any explicit Deploy mutation.

## Design goals

- Release truth: only a terminal forge-release/v2 record with component receipts proves that a platform release is deployed.
- Headless by default: JSON and JSONL are stable contracts; progress and failures are machine-actionable.
- Least privilege: credentials are repository-scoped, and platform operations live behind a separate operator capability.
- Explicit safety: reads never mutate; retries, promotion, rollback, cancellation, and canary pushes require an explicit command and confirmation.

## Jump to a command

Use the sections below to jump directly to a command. Every command documents its access scope, safety behavior, output schema, exit codes, and remediation.

### Discover and document

- [`sf help`](#sf-help) — Describe a command or the complete CLI.
- [`sf commands`](#sf-commands) — List command paths for machine discovery.
- [`sf schema`](#sf-schema) — Print the versioned CLI command manifest.
- [`sf docs generate`](#sf-docs-generate) — Generate CLI reference artifacts from the registry.

### Authentication

- [`sf auth status`](#sf-auth-status) — Show the active credential without exposing it.
- [`sf auth login`](#sf-auth-login) — Authenticate a Forge CLI session.
- [`sf auth logout`](#sf-auth-logout) — Remove this machine’s stored Forge credentials.
- [`sf auth revoke`](#sf-auth-revoke) — Revoke a personal access token.
- [`sf whoami`](#sf-whoami) — Return the authenticated Forge identity.
- [`sf scopes`](#sf-scopes) — Show the active credential scopes.
- [`sf register`](#sf-register) — Register a Forge account.

### Repository state and Git

- [`sf git doctor`](#sf-git-doctor) — Diagnose Forge Smart HTTP repository access.
- [`sf repo create`](#sf-repo-create) — Create a repository.
- [`sf repo list`](#sf-repo-list) — List repositories.
- [`sf repo get`](#sf-repo-get) — Get a repository.
- [`sf repo update`](#sf-repo-update) — Update a repository.
- [`sf repo star`](#sf-repo-star) — Star a repository.
- [`sf repo unstar`](#sf-repo-unstar) — Unstar a repository.
- [`sf repo import`](#sf-repo-import) — Import repositories.
- [`sf clone-url`](#sf-clone-url) — Print a clone URL.
- [`sf migrate`](#sf-migrate) — Inspect or migrate a local repository configuration.

### Actions

- [`sf actions list`](#sf-actions-list) — List Actions runs.
- [`sf actions inspect`](#sf-actions-inspect) — Inspect an Action run and linked release receipt.
- [`sf actions cancel`](#sf-actions-cancel) — Cancel an Action run.

### Other workflows

- [`sf agent profiles`](#sf-agent-profiles) — List repository-agent execution profiles.
- [`sf agent list`](#sf-agent-list) — List durable repository-agent threads.
- [`sf agent create`](#sf-agent-create) — Create or recover a durable repository-agent thread.
- [`sf agent view`](#sf-agent-view) — Inspect one durable repository-agent thread.
- [`sf agent message`](#sf-agent-message) — Message a repository agent at an explicit execution tier.
- [`sf agent events`](#sf-agent-events) — Read normalized repository-agent events after a cursor.
- [`sf agent cancel`](#sf-agent-cancel) — Cancel one repository-agent run.
- [`sf agent approve`](#sf-agent-approve) — Resolve one repository-agent approval.
- [`sf release enqueue`](#sf-release-enqueue) — Submit an exact feature SHA to the protected production merge queue.
- [`sf release status`](#sf-release-status) — Read canonical forge-release/v2 state.
- [`sf release watch`](#sf-release-watch) — Watch one canonical request through merge and release until terminal.
- [`sf benchmark`](#sf-benchmark) — Plan or run an exact-tree Forge/GitHub benchmark.
- [`sf gist import`](#sf-gist-import) — Import GitHub Gists.
- [`sf transcript upload`](#sf-transcript-upload) — Upload an agent transcript.
- [`sf hooks install`](#sf-hooks-install) — Install repository hooks.
- [`sf hooks status`](#sf-hooks-status) — Inspect repository hooks.
- [`sf llms`](#sf-llms) — Fetch llms.txt.

### Pull requests

- [`sf pr list`](#sf-pr-list) — List pull requests.
- [`sf pr view`](#sf-pr-view) — Inspect a pull request.
- [`sf pr create`](#sf-pr-create) — Create a pull request.

### Deploy

- [`sf deploy list`](#sf-deploy-list) — List generalized Deploy projects and releases.
- [`sf deploy status`](#sf-deploy-status) — Show a generalized Deploy release and production evidence.
- [`sf deploy retry`](#sf-deploy-retry) — Request an explicit generalized Deploy build.
- [`sf deploy promote`](#sf-deploy-promote) — Promote a verified release with current-pointer fencing.
- [`sf deploy rollback`](#sf-deploy-rollback) — Restore a selected verified release with fencing.
- [`sf deploy check`](#sf-deploy-check) — Validate a local forgeBuild.ts.

### Diagnostics

- [`sf diagnose`](#sf-diagnose) — Retrieve a sanitized release or ingest diagnostic.

## Command reference

## `sf help`

Describe a command or the complete CLI.

Command help is generated from this registry. JSON help is safe for agents and documentation generators.

- Access: none
- Safety: read-only; Always safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.help.v1` — Command metadata or the complete manifest.
- Exit codes: 0, 64
- Arguments: `command?`
- Flags: `--json`

Examples:

```sh
sf help status
```

```sh
sf help --json
```

Remediation: Run `sf commands --json` to discover canonical paths.

## `sf commands`

List command paths for machine discovery.

Returns registry-defined commands without parsing human console output.

- Access: none
- Safety: read-only; Always safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.commands.v1` — Canonical paths, aliases, summaries, and safety class.
- Exit codes: 0
- Flags: `--json`

Examples:

```sh
sf commands --json
```

## `sf schema`

Print the versioned CLI command manifest.

The versioned manifest is canonical input for website documentation and coding agents.

- Access: none
- Safety: read-only; Always safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.manifest.v1` — Complete stable command manifest.
- Exit codes: 0
- Flags: `--json`

Examples:

```sh
sf schema
```

## `sf docs generate`

Generate CLI reference artifacts from the registry.

Writes the website-consumable JSON manifest and Markdown reference. `--check` detects drift without writing.

- Access: none
- Safety: mutating; Deterministic; safe to rerun.
- Confirmation: Never prompts.
- Output: `forge.cli.docs.v1` — Artifact paths and whether they were current.
- Exit codes: 0, 65
- Flags: `--check`

Examples:

```sh
sf docs generate
```

```sh
sf docs generate --check
```

Remediation: Run `sf docs generate` and commit both generated artifacts.

## `sf auth status`

Show the active credential without exposing it.

Reports the configured identity, credential storage state, and server-confirmed authentication state.

- Access: none
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.auth.status.v1` — Sanitized credential and identity metadata.
- Exit codes: 0, 10
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf auth status --json
```

Remediation: Run `sf auth login` or set a short-lived SMOLFORGE_TOKEN.

## `sf auth login`

Authenticate a Forge CLI session.

Prompts for a missing username or email in a TTY, stores the bearer credential in the OS keychain, and installs a Forge-only Git credential helper. The helper mints short-lived repository credentials on demand without changing remotes or generic Git helpers.

Aliases: `sf login`.

- Access: none
- Safety: mutating; Creates or replaces only local credential storage.
- Confirmation: Resolves identity before reading a password; JSON mode requires explicit environment inputs and never prompts.
- Output: `forge.auth.login.v1` — Sanitized authenticated identity and installed Forge Git helper.
- Exit codes: 0, 10, 64
- Flags: `--json`, `--jsonl`, `--base-url`, `--username`, `--email`

Examples:

```sh
sf auth login
```

```sh
sf auth login --username alice
```

Remediation: Use browser/device login when enabled, or pass explicit credentials only in a trusted environment.

## `sf auth logout`

Remove this machine’s stored Forge credentials.

Revokes all repository credentials minted by this CLI, removes the Forge-only Git helper, and deletes the local session keychain credential. If token revocation fails, logout stops so it can be retried safely.

- Access: none
- Safety: mutating; Safe to retry; token revocation completes before local credentials are removed.
- Confirmation: Never prompts.
- Output: `forge.auth.logout.v1` — Whether the session and helper-issued Git credentials were removed.
- Exit codes: 0, 10, 13
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf auth logout --json
```

Remediation: Retry `sf auth logout` while the session is still available.

## `sf auth revoke`

Revoke a personal access token.

Revokes a listed PAT using the current session credential.

- Access: none
- Safety: mutating; Safe: already-revoked credentials remain unusable.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.auth.revoke.v1` — Revoked credential identifier.
- Exit codes: 0, 10, 64
- Arguments: `token-id`
- Flags: `--json`, `--jsonl`, `--base-url`, `--yes`

Examples:

```sh
sf auth revoke pat_id --yes
```

Remediation: List tokens in the Forge account before retrying.

## `sf whoami`

Return the authenticated Forge identity.

A server-authoritative identity check.

- Access: none
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.auth.whoami.v1` — Authenticated identity.
- Exit codes: 0, 10
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf whoami --json
```

Remediation: Run `sf auth login`.

## `sf scopes`

Show the active credential scopes.

Returns only caller-visible authorization scope metadata.

- Access: none
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.auth.scopes.v1` — Current auth type and scopes.
- Exit codes: 0, 10
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf scopes --json
```

Remediation: Mint a repository-scoped credential with the minimal required scopes.

## `sf git doctor`

Diagnose Forge Smart HTTP repository access.

Checks local remote/ref agreement, repository-scoped authorization, and real ls-remote behavior. A clean canary push is explicit and never implicit.

- Access: `repo:read`
- Safety: read-only; Read-only by default. Canary behavior is explicit and separately fenced.
- Confirmation: Canary requires --canary-push --yes.
- Output: `forge.git.doctor.v1` — Scoped Git authorization and ref diagnostic.
- Exit codes: 0, 10, 11, 12
- Arguments: `owner/repo?`
- Flags: `--json`, `--jsonl`, `--base-url`, `--canary-push`, `--yes`

Examples:

```sh
sf git doctor --json
```

Remediation: Run `sf auth login` and retry.

## `sf actions list`

List Actions runs.

Lists scoped runs with SHA, actor, conclusion, and linked Deploy delivery evidence.

Aliases: `sf actions runs`.

- Access: `actions:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.actions.list.v1` — Runs with delivery evidence.
- Exit codes: 0, 10
- Arguments: `owner/repo?`
- Flags: `--json`, `--jsonl`, `--base-url`, `--limit`, `--status`, `--watch`

Examples:

```sh
sf actions list --json
```

Remediation: Use `sf actions inspect` for a particular run.

## `sf actions inspect`

Inspect an Action run and linked release receipt.

Includes jobs, steps, timings, cache evidence, logs summary, and Deploy delivery state.

Aliases: `sf actions explain`.

- Access: `actions:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.actions.inspect.v1` — Action and release receipt evidence.
- Exit codes: 0, 10, 11
- Arguments: `owner/repo?`, `run-id`
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf actions inspect owner/repo 42 --json
```

Remediation: Use `sf actions list` to find an accessible run.

## `sf actions cancel`

Cancel an Action run.

Explicitly cancels a cancellable run; no retry or deploy repair is implied.

- Access: `actions:write`
- Safety: mutating; Safe only where the server reports a terminal cancellation state.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.actions.cancel.v1` — Cancelled run state.
- Exit codes: 0, 12, 64
- Arguments: `owner/repo`, `run-id`
- Flags: `--json`, `--jsonl`, `--base-url`, `--yes`

Examples:

```sh
sf actions cancel owner/repo 42 --yes
```

Remediation: Inspect the run before cancelling.

## `sf agent profiles`

List repository-agent execution profiles.

Shows live Instant and allowlisted Workspace availability, capabilities, and backend reasons for one repository.

- Access: `agent:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.agent.profiles.v1` — Execution ladder and live availability.
- Exit codes: 0, 10, 11, 64
- Arguments: `owner/repo`
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf agent profiles owner/repo --json
```

Remediation: Confirm repository access and inspect unavailable_reason before selecting a tier.

## `sf agent list`

List durable repository-agent threads.

Lists private thread handles without returning another repository’s conversations.

- Access: `agent:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.agent.list.v1` — Repository-scoped agent threads.
- Exit codes: 0, 10, 11, 64
- Arguments: `owner/repo`
- Flags: `--json`, `--jsonl`, `--base-url`, `--limit`

Examples:

```sh
sf agent list owner/repo --json
```

Remediation: Use `sf agent create` to start a thread.

## `sf agent create`

Create or recover a durable repository-agent thread.

Creates a repository-scoped thread or idempotently returns the caller-selected thread handle.

- Access: `agent:run`
- Safety: mutating; Idempotent when --thread-id is reused by the same repository actor.
- Confirmation: Never prompts.
- Output: `forge.agent.create.v1` — Created or recovered thread.
- Exit codes: 0, 10, 12, 64
- Arguments: `owner/repo`
- Flags: `--json`, `--jsonl`, `--base-url`, `--thread-id`

Examples:

```sh
sf agent create owner/repo --json
```

Remediation: Keep the returned thread_id for later messages.

## `sf agent view`

Inspect one durable repository-agent thread.

Returns messages, runs, approvals, artifacts, and immutable receipts for the selected thread.

- Access: `agent:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.agent.view.v1` — Authoritative thread state and receipts.
- Exit codes: 0, 10, 11, 64
- Arguments: `owner/repo`, `thread-id`
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf agent view owner/repo agent_thread_0123456789abcdef0123456789abcdef --json
```

Remediation: Use `sf agent list` to find the thread.

## `sf agent message`

Message a repository agent at an explicit execution tier.

Creates a thread when needed, freezes the selected source ref, and submits Auto, Instant, or allowlisted Workspace work without changing thread identity.

- Access: `agent:message`
- Safety: mutating; Use --client-message-id to replay the same normalized message safely.
- Confirmation: Never prompts; Workspace remains server-allowlisted.
- Output: `forge.agent.message.v1` — Accepted message, frozen run, thread handle, and events URL.
- Exit codes: 0, 10, 11, 12, 13, 64
- Arguments: `owner/repo`
- Flags: `--json`, `--jsonl`, `--base-url`, `--message`, `--thread`, `--mode`, `--max-compute`, `--source-ref`, `--client-message-id`

Examples:

```sh
sf agent message owner/repo --message "Explain this module" --mode instant --json
```

```sh
sf agent message owner/repo --thread agent_thread_0123456789abcdef0123456789abcdef --message "Implement and test it" --mode workspace --json
```

Remediation: Inspect `sf agent profiles`; Workspace additionally requires agent:write, repository write permission, and an Alpha allowlist match.

## `sf agent events`

Read normalized repository-agent events after a cursor.

Reads durable progress, approval, artifact, and terminal events without polling provider-private state.

- Access: `agent:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.agent.events.v1` — Normalized durable event page.
- Exit codes: 0, 10, 11, 64
- Arguments: `owner/repo`, `thread-id`
- Flags: `--json`, `--jsonl`, `--base-url`, `--after`, `--limit`

Examples:

```sh
sf agent events owner/repo agent_thread_0123456789abcdef0123456789abcdef --after 0 --json
```

Remediation: Resume from the returned cursor.

## `sf agent cancel`

Cancel one repository-agent run.

Requests cancellation for the exact thread/run pair; Workspace teardown and publication fencing remain server-owned.

- Access: `agent:cancel`
- Safety: mutating; Safe to repeat after the server records the terminal run.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.agent.cancel.v1` — Cancellation request and run state.
- Exit codes: 0, 10, 11, 12, 64
- Arguments: `owner/repo`, `thread-id`, `run-id`
- Flags: `--json`, `--jsonl`, `--base-url`, `--yes`

Examples:

```sh
sf agent cancel owner/repo agent_thread_0123456789abcdef0123456789abcdef agent_run_0123456789abcdef0123456789abcdef --yes --json
```

Remediation: Inspect the thread receipt to confirm teardown.

## `sf agent approve`

Resolve one repository-agent approval.

Resolves the exact approval inside its repository, thread, and run authority without broadening future actions.

- Access: `agent:approve`
- Safety: mutating; The same decision replays; a conflicting decision is rejected.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.agent.approve.v1` — Resolved approval and authoritative run state.
- Exit codes: 0, 10, 11, 12, 64
- Arguments: `owner/repo`, `thread-id`, `run-id`, `approval-id`
- Flags: `--json`, `--jsonl`, `--base-url`, `--decision`, `--note`, `--yes`

Examples:

```sh
sf agent approve owner/repo agent_thread_0123456789abcdef0123456789abcdef agent_run_0123456789abcdef0123456789abcdef agent_approval_0123456789abcdef0123456789abcdef --decision approve_once --yes --json
```

Remediation: Refresh the thread before resolving a conflicting decision.

## `sf pr list`

List pull requests.

Lists pull requests without requiring a browser.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.pr.list.v1` — Pull requests and pagination.
- Exit codes: 0, 10, 11, 64
- Arguments: `owner/repo?`
- Flags: `--json`, `--jsonl`, `--base-url`, `--state`

Examples:

```sh
sf pr list owner/repo --state open --json
```

Remediation: Check the repository name and credential scope.

## `sf pr view`

Inspect a pull request.

Returns pull request metadata, commits, and the exact unified diff.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.pr.view.v1` — Pull request metadata, commits, and diff.
- Exit codes: 0, 10, 11, 64
- Arguments: `owner/repo`, `number`
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf pr view owner/repo 7 --json
```

Remediation: Use `sf pr list` to find an accessible pull request.

## `sf pr create`

Create a pull request.

Creates a pull request from explicit source and target branches without opening a browser.

- Access: `repo:write`
- Safety: mutating; Not automatically idempotent; inspect existing pull requests before retrying an uncertain response.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.pr.create.v1` — Created pull request.
- Exit codes: 0, 10, 11, 12, 64
- Arguments: `owner/repo`
- Flags: `--json`, `--jsonl`, `--base-url`, `--head`, `--base`, `--title`, `--body`, `--yes`

Examples:

```sh
sf pr create owner/repo --head feature --base main --title "Add feature" --yes
```

Remediation: Run `sf pr list` before retrying after an uncertain response.

## `sf deploy list`

List generalized Deploy projects and releases.

Reads the authoritative generalized Deploy release ledger.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.deploy.list.v1` — Projects and current release evidence.
- Exit codes: 0, 10
- Arguments: `owner/repo?`
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf deploy list --json
```

Remediation: Configure a Deploy project for the repository.

## `sf deploy status`

Show a generalized Deploy release and production evidence.

Shows release, provider version, binding, endpoint, and activation evidence without treating an upload as live.

Aliases: `sf deploy show`.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.deploy.status.v1` — Release and production pointer evidence.
- Exit codes: 0, 11
- Arguments: `owner/repo?`
- Flags: `--json`, `--jsonl`, `--base-url`, `--project`, `--release`, `--watch`

Examples:

```sh
sf deploy status --project project_id --json
```

Remediation: Use `sf deploy list`.

## `sf deploy retry`

Request an explicit generalized Deploy build.

Uses an idempotency key and only requests the current project head; it never replays an uncertain repository command.

- Access: `repo:write`
- Safety: mutating; Server-enforced by Idempotency-Key; only current HEAD is eligible.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.deploy.retry.v1` — Release ID, source SHA, and replay status.
- Exit codes: 0, 12, 13, 64
- Arguments: `owner/repo`
- Flags: `--json`, `--jsonl`, `--base-url`, `--project`, `--idempotency-key`, `--yes`

Examples:

```sh
sf deploy retry owner/repo --project id --idempotency-key repair-123 --yes
```

Remediation: Use `sf diagnose` before a retry after repository commands have started.

## `sf deploy promote`

Promote a verified release with current-pointer fencing.

Activates a selected generalized release only when expected current production state still matches.

- Access: `repo:write`
- Safety: mutating; Fenced; stale current-pointer attempts conflict.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.deploy.promote.v1` — Activation receipt and provider evidence.
- Exit codes: 0, 12, 64
- Arguments: `owner/repo`
- Flags: `--json`, `--jsonl`, `--base-url`, `--project`, `--release`, `--expected-current`, `--yes`

Examples:

```sh
sf deploy promote owner/repo --project id --release id --expected-current deployment --yes
```

Remediation: Refresh `sf deploy status` and retry with the new pointer.

## `sf deploy rollback`

Restore a selected verified release with fencing.

Rolls production back only to a selected release and expected current pointer.

- Access: `repo:write`
- Safety: mutating; Fenced; compensation runs once per confirmed operation.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.deploy.rollback.v1` — Rollback activation receipt.
- Exit codes: 0, 12, 64
- Arguments: `owner/repo`
- Flags: `--json`, `--jsonl`, `--base-url`, `--project`, `--release`, `--expected-current`, `--yes`

Examples:

```sh
sf deploy rollback owner/repo --project id --release id --expected-current deployment --yes
```

Remediation: Refresh `sf deploy status` before retrying.

## `sf diagnose`

Retrieve a sanitized release or ingest diagnostic.

Resolves a 32-character Git ingest request ID independently of the current checkout. Release and deployment diagnostics remain repository-scoped. Returns the authorized phase, retryability, affected SHA/release/run, and next safe action.

- Access: `repo:read`
- Safety: read-only; Safe to retry; watch mode performs only bounded reads.
- Confirmation: Never prompts.
- Output: `forge.diagnose.v1` — Sanitized caller-authorized diagnostic.
- Exit codes: 0, 11, 14, 64
- Arguments: `operation-or-ingest-id`
- Flags: `--json`, `--jsonl`, `--base-url`, `--repo`, `--watch`, `--timeout`

Examples:

```sh
sf diagnose ingest_id --watch --json
```

```sh
sf diagnose release_id --repo owner/repo --json
```

Remediation: Use the ID returned by release status, Git, Actions, or Deploy output.

## `sf release enqueue`

Submit an exact feature SHA to the protected production merge queue.

Records the immutable pull-request candidate, dispatches affected CI, verifies server-signed evidence, merges through the protected queue, and hands the resulting main SHA to the resumable fenced controller. It never activates a provider inline.

- Access: `repo:write`
- Safety: mutating; Idempotent by environment, pull request, and exact source SHA; duplicate submissions return the existing request.
- Confirmation: Requires --yes outside a TTY.
- Output: `forge.release.enqueue.v2` — Canonical request identity and queue state.
- Exit codes: 0, 10, 12, 64
- Arguments: `sha`
- Flags: `--json`, `--jsonl`, `--base-url`, `--ref`, `--repo`, `--pr`, `--yes`

Examples:

```sh
sf release enqueue $SHA --ref codex/my-feature --repo swyx/forge --pr 5 --yes --json
```

Remediation: Confirm the branch has an open ready pull request, or query `sf release status`.

## `sf release status`

Read canonical forge-release/v2 state.

Returns the durable merge request or release record, current phase, append-only phase history, and receipt summaries. A request ID plus --repo uses ordinary repository read permission; the operator-only list omits --repo.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.release.status.v2` — Canonical release queue and receipt state.
- Exit codes: 0, 10, 11
- Arguments: `release-id?`
- Flags: `--json`, `--jsonl`, `--base-url`, `--repo`, `--environment`

Examples:

```sh
sf release status fmq_id --repo swyx/forge --json
```

```sh
sf release status --json
```

Remediation: Use the request ID returned by enqueue and the same --repo value.

## `sf release watch`

Watch one canonical request through merge and release until terminal.

Polls only the forge-release/v2 status API with bounded exponential backoff. It performs no provider or workflow mutation.

- Access: `repo:read`
- Safety: read-only; Read-only and safe to retry.
- Confirmation: Never prompts.
- Output: `forge.release.status.v2` — Terminal canonical release status.
- Exit codes: 0, 10, 11, 14, 64
- Arguments: `release-id`
- Flags: `--json`, `--jsonl`, `--base-url`, `--repo`, `--environment`, `--timeout`

Examples:

```sh
sf release watch fmq_id --repo swyx/forge --json
```

Remediation: Run `sf release status <request-id> --repo owner/name` for the latest phase.

## `sf deploy check`

Validate a local forgeBuild.ts.

Statically validates the checked-in Forge Deploy configuration.

- Access: none
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.deploy.check.v1` — Normalized local config validation.
- Exit codes: 0, 64
- Arguments: `path?`
- Flags: `--json`, `--jsonl`, `--base-url`

Examples:

```sh
sf deploy check
```

```sh
sf deploy check --json
```

Remediation: Fix the cited forgeBuild.ts constraint.

## `sf benchmark`

Plan or run an exact-tree Forge/GitHub benchmark.

Uses a packaged fixture and refuses source drift. The executable transport matrix is read-only and creates only local temporary clones. Cold-push and build scenarios remain gated on server-issued ephemeral namespaces so this command cannot create permanent repositories, attach targets, or promote.

- Access: none
- Safety: read-only; Read-only remote operations; local temporary clones are removed after each run.
- Confirmation: Never prompts. Execution requires --execute and an explicit Forge URL.
- Output: `forge.benchmark.result.v1` — Exact fixture identity, scenario policy, provider samples, median, and p95.
- Exit codes: 0, 12, 64, 65
- Arguments: `fixture`
- Flags: `--json`, `--jsonl`, `--base-url`, `--forge-url`, `--github-url`, `--sha`, `--samples`, `--execute`

Examples:

```sh
sf benchmark swyxkit --json
```

```sh
sf benchmark swyxdotio --forge-url https://forge.smol.ai/owner/mirror.git --execute --samples 5 --json
```

Remediation: Refresh the fixture SHA only after both remotes expose the same exact tree.

## `sf register`

Register a Forge account.

Register a Forge account.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf register
```

Remediation: Run `sf help` for the current arguments.

## `sf repo create`

Create a repository.

Create a repository.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf repo create
```

Remediation: Run `sf help` for the current arguments.

## `sf repo list`

List repositories.

List repositories.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf repo list
```

Remediation: Run `sf help` for the current arguments.

## `sf repo get`

Get a repository.

Get a repository.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf repo get
```

Remediation: Run `sf help` for the current arguments.

## `sf repo update`

Update a repository.

Update a repository.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf repo update
```

Remediation: Run `sf help` for the current arguments.

## `sf repo star`

Star a repository.

Star a repository.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf repo star
```

Remediation: Run `sf help` for the current arguments.

## `sf repo unstar`

Unstar a repository.

Unstar a repository.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf repo unstar
```

Remediation: Run `sf help` for the current arguments.

## `sf repo import`

Import repositories.

Import repositories.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf repo import
```

Remediation: Run `sf help` for the current arguments.

## `sf gist import`

Import GitHub Gists.

Import GitHub Gists.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf gist import
```

Remediation: Run `sf help` for the current arguments.

## `sf clone-url`

Print a clone URL.

Print a clone URL.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf clone-url
```

Remediation: Run `sf help` for the current arguments.

## `sf transcript upload`

Upload an agent transcript.

Upload an agent transcript.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf transcript upload
```

Remediation: Run `sf help` for the current arguments.

## `sf hooks install`

Install repository hooks.

Install repository hooks.

- Access: `repo:read`
- Safety: mutating; See the command response for operation-specific retry semantics.
- Confirmation: Use explicit command flags where supported.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf hooks install
```

Remediation: Run `sf help` for the current arguments.

## `sf hooks status`

Inspect repository hooks.

Inspect repository hooks.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf hooks status
```

Remediation: Run `sf help` for the current arguments.

## `sf migrate`

Inspect or migrate a local repository configuration.

Inspect or migrate a local repository configuration.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf migrate
```

Remediation: Run `sf help` for the current arguments.

## `sf llms`

Fetch llms.txt.

Fetch llms.txt.

- Access: `repo:read`
- Safety: read-only; Safe to retry.
- Confirmation: Never prompts.
- Output: `forge.cli.response.v1` — Command response.
- Exit codes: 0, 10, 64

Examples:

```sh
sf llms
```

Remediation: Run `sf help` for the current arguments.