DocsStart hereForge CLI

Opening the page…

Heating the forge…

DocsStart hereForge CLI

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.

Quick start#

Forge CLI is the headless interface for coding agents and the concise command line for humans who submit serialized merges and observe exact-SHA production attempts.

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.

Authenticate: sf auth login — Create or refresh this machine’s Forge session in protected OS storage without printing its credential.
Inspect a release: sf release status — Read the serialized merge and its latest exact-SHA production attempt.
Wait without mutating: sf release watch — Watch one attempt until terminal. This never pushes, retries, activates, or rolls back.
Diagnose before repair: 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 successful exact-SHA attempt with its compact receipt proves a platform release is deployed.
Headless by default: JSON and JSONL are stable contracts; progress and failures are machine-actionable.
Explicit credential boundary: normal sessions use protected OS storage, while Git uses separate repository-scoped credentials.
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 — Describe a command or the complete CLI.
sf commands — List command paths for machine discovery.
sf schema — Print the versioned CLI command manifest.
sf docs generate — Generate CLI reference artifacts from the registry.

Authentication#

sf auth status — Show the active credential without exposing it.
sf auth login — Authenticate a Forge CLI session.
sf auth bridge — Copy a protected Forge session to explicit sandbox file storage.
sf auth git-credential — Prepare repository-scoped credentials for Git.
sf auth logout — Remove this machine’s stored Forge credentials.
sf auth revoke — Revoke a personal access token.
sf whoami — Return the authenticated Forge identity.
sf scopes — Show the active credential scopes.
sf register — Register a Forge account.

Repository state and Git#

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

Actions#

sf actions list — List Actions runs.
sf actions inspect — Inspect an Action run and linked release receipt.
sf actions cancel — Cancel an Action run.

Other workflows#

sf agent profiles — List repository-agent execution profiles.
sf agent list — List durable repository-agent threads.
sf agent create — Create or recover a durable repository-agent thread.
sf agent view — Inspect one durable repository-agent thread.
sf agent message — Message a repository agent at an explicit execution tier.
sf agent events — Read normalized repository-agent events after a cursor.
sf agent cancel — Cancel one repository-agent run.
sf agent approve — Resolve one repository-agent approval.
sf content create — Create an account or repository Content publication.
sf content attach — Move an existing publication into a repository scope.
sf content list — List an editorial publication and its draft documents.
sf content get — Read one published Content document.
sf content draft — Create an immutable Content draft revision.
sf content draft pull — Fetch the selected Content draft for local or agent work.
sf content draft push — Push an immutable Content draft revision.
sf content draft diff — Diff two immutable Content revisions.
sf content draft preview — Preview the selected Content draft safely.
sf content history — List immutable revisions for a Content document.
sf content comments — List Content review threads.
sf content comment add — Create a range, block, document, or screenshot review thread.
sf content comment reply — Reply to a Content review thread.
sf content comment resolve — Resolve a Content review thread.
sf content comment assign — Assign a review thread to an explicitly granted agent.
sf content publish — Atomically select a Content publication release.
sf content release status — List Content publication releases.
sf content rollback — Move a publication pointer to a prior immutable release.
sf content grant — Grant a service principal a Content publication role.
sf content inspect — Inspect a Markdown file before Content import.
sf content import — Import one file or a Markdown/MDX directory as immutable Content drafts.
sf release enqueue — Submit an exact feature SHA to the serialized production merge queue.
sf release status — Read canonical merge or production-deployment state.
sf release watch — Watch one merge or project deployment until terminal.
sf observe install — Install the local skill observability collector.
sf observe status — Status the local skill observability collector.
sf observe doctor — Doctor the local skill observability collector.
sf observe uninstall — Uninstall the local skill observability collector.
sf add skit — Install a complete SKIT release.
sf skit init — Create a single-skill SKIT scaffold.
sf skit validate — Validate bundle declarations, files, hashes, and static audit.
sf skit publish — Publish the current valid draft as an immutable release.
sf skit pull — Resolve and install a SKIT source.
sf skit enable — Enable and project one contained skill.
sf skit disable — Disable one contained skill without altering its bundle.
sf skit update — Update one or all installed SKITs from recorded sources.
sf skit remove — Remove clean managed projections and local desired state.
sf skit list — List Forge-managed local SKIT installations.
sf skit sync — Validate and three-way reconcile a bound editable draft.
sf skit inventory — Rescan known agent roots without changing projections.
sf skit reconcile — Apply only safe non-conflicting desired-state changes.
sf skit doctor — Diagnose local library, adapter, and projection state.
sf benchmark — Plan or run an exact-tree Forge/GitHub benchmark.
sf transcript upload — Upload an agent transcript.
sf hooks install — Install repository hooks.
sf hooks status — Inspect repository hooks.
sf llms — Fetch llms.txt.

Pull requests#

sf pr list — List pull requests.
sf pr view — Inspect a pull request.
sf pr create — Create a pull request.

Deploy#

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

Diagnostics#

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:

sf help status

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:

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:

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:

sf docs generate

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 API authentication state. When owner/repo is supplied, or exactly one HTTPS Forge remote is present, it separately diagnoses the repository-scoped Git helper and credential without exposing either bearer.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.auth.status.v1 — Sanitized API identity plus separate repository Git-wiring state.
Exit codes: 0, 10, 64
Arguments: owner/repo?
Flags: --json, --jsonl, --base-url

Examples:

sf auth status --json

sf auth status owner/repo --json

Remediation: Run sf auth login or set a short-lived SMOLFORGE_TOKEN. To inspect Git access explicitly, run sf auth status owner/repo.

`sf auth login`#

Authenticate a Forge CLI session.

Prompts for a missing username or email in a TTY and stores the full-access Forge session in protected OS storage by default. Normal Git setup remains repository-scoped and its credentials last seven days. A trusted durable machine may explicitly request a global, non-expiring Git credential with --git-scope global --expires never --yes. That credential covers every accessible Forge repository, is stored only in protected OS storage, is never printed, and is revoked by sf auth logout. Use --storage file only for the login session in a local sandbox; it cannot be combined with durable global Git access.

Aliases: sf login.

Access: none
Safety: mutating; Creates or replaces the selected local login session. Durable mode replaces the prior CLI-managed global Git credential.
Confirmation: Durable global Git access requires the exact scope/expiry flags plus --yes; validation and confirmation happen before password input or remote mutation.
Output: forge.auth.login.v1 — Sanitized authenticated identity, selected login storage, and Git credential mode; never either bearer.
Exit codes: 0, 10, 64
Flags: --json, --jsonl, --base-url, --username, --email, --storage, --git-scope, --expires, --yes

Examples:

sf auth login

sf auth login --username alice

sf auth login --storage file

sf auth login --git-scope global --expires never --yes

Remediation: Use ordinary login for least privilege, or review and explicitly run sf auth login --git-scope global --expires never --yes on a trusted durable machine.

`sf auth bridge`#

Copy a protected Forge session to explicit sandbox file storage.

Copies only the protected host credential to ~/.smolforge/credentials.json for sandbox access; it does not change normal host storage. The file copy grants full Forge account access to a process that can read it. The command reports the copied session expiry when recorded. sf auth logout removes local copies and reports if protected-store cleanup cannot be confirmed, but does not remotely revoke an already-copied session.

Access: none
Safety: mutating; Replaces only the explicit file copy for the selected Forge origin.
Confirmation: Never prompts. Running this command is explicit consent to make the full-access session readable by a local sandbox or coding agent.
Output: forge.auth.bridge.v1 — Sanitized sandbox credential-file path and session-expiry metadata; never the bearer.
Exit codes: 0, 10, 64
Flags: --json, --jsonl, --base-url

Examples:

sf auth bridge

Remediation: Run sf auth login to create a protected host session, then retry sf auth bridge.

`sf auth git-credential`#

Prepare repository-scoped credentials for Git.

Installs the Forge-only URL-scoped Git credential helper and prepares a seven-day repository credential. Pass owner/repo, or omit it only inside a checkout with exactly one unambiguous HTTPS Forge remote; multiple or mixed Forge remotes are rejected locally. An explicitly configured durable global credential satisfies this setup without minting another token. It does not expose the full Forge session, rewrite Git remotes, or replace unrelated Git credential helpers.

Access: repo:read, repo:write
Safety: mutating; Reuses a valid repository credential. When the helper and scoped credential are already configured, it performs no Git-config write or token mint.
Confirmation: Never prompts. Validates repository resolution and selected credential storage before changing Git configuration or minting a repository token.
Output: forge.auth.git-credential.v1 — Sanitized repository source, helper/configuration state, storage, and credential-expiry metadata; never the bearer.
Exit codes: 0, 10, 11, 64
Arguments: owner/repo?
Flags: --json, --jsonl, --base-url, --storage

Examples:

sf auth git-credential owner/repo

sf auth git-credential

sf auth git-credential owner/repo --storage file --json

Remediation: Run sf auth login, then retry with sf auth git-credential owner/repo. In a local sandbox without protected storage, deliberately use --storage file.

`sf auth logout`#

Remove this machine’s stored Forge credentials.

Revokes every repository-scoped or durable global Git credential minted by this CLI, removes the Forge-only Git helper, and deletes local Forge session copies from protected OS storage, ~/.smolforge/credentials.json, and any explicitly file-stored repository credentials in ~/.smolforge/git-credentials.json. It removes local copies but does not remotely revoke an already-copied Forge session; it reports an error if protected-store cleanup cannot be confirmed. If Git-token revocation fails, logout stops so it can be retried safely.

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

Examples:

sf auth logout --json

Remediation: Retry sf auth logout while the session is still available. If it reports protected-store cleanup failure, restore that store and retry; any explicit credential file copy was still removed.

`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:

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:

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:

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:

sf git doctor --json

Remediation: Run sf auth login, then sf auth git-credential owner/repo, and retry.

`sf actions list`#

List Actions runs.

Lists scoped runs with SHA, actor, conclusion, and linked Deploy delivery evidence. --branch selects one exact workflow trigger branch; a canonical refs/heads/... input is normalized to that branch name.

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, 64
Arguments: owner/repo?
Flags: --json, --jsonl, --base-url, --limit, --status, --branch

Examples:

sf actions list --json

sf actions list owner/repo --branch codex/repo-rename-redirect --json

Remediation: Use --branch with one exact branch, or 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:

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:

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:

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:

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:

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:

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:

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

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:

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:

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:

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 content create`#

Create an account or repository Content publication.

Create an account or repository Content publication. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCreate.v1 — Create an account or repository Content publication..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url, --repo, --org, --title, --description, --visibility

Examples:

sf content create --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content attach`#

Move an existing publication into a repository scope.

Move an existing publication into a repository scope. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentAttach.v1 — Move an existing publication into a repository scope..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url, --repo, --slug

Examples:

sf content attach --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content list`#

List an editorial publication and its draft documents.

List an editorial publication and its draft documents. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentList.v1 — List an editorial publication and its draft documents..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content list --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content get`#

Read one published Content document.

Read one published Content document. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentGet.v1 — Read one published Content document..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content get --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft`#

Create an immutable Content draft revision.

Create an immutable Content draft revision. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentDraft.v1 — Create an immutable Content draft revision..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url, --slug, --title, --file, --metadata, --base-revision, --description, --collection

Examples:

sf content draft --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft pull`#

Fetch the selected Content draft for local or agent work.

Fetch the selected Content draft for local or agent work. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentDraftPull.v1 — Fetch the selected Content draft for local or agent work..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content draft pull --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft push`#

Push an immutable Content draft revision.

Push an immutable Content draft revision. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentDraft.v1 — Push an immutable Content draft revision..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content draft push --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft diff`#

Diff two immutable Content revisions.

Diff two immutable Content revisions. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentDraftDiff.v1 — Diff two immutable Content revisions..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content draft diff --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft preview`#

Preview the selected Content draft safely.

Preview the selected Content draft safely. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentDraftPreview.v1 — Preview the selected Content draft safely..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content draft preview --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content history`#

List immutable revisions for a Content document.

List immutable revisions for a Content document. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentHistory.v1 — List immutable revisions for a Content document..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content history --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comments`#

List Content review threads.

List Content review threads. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentComments.v1 — List Content review threads..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comments --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comment add`#

Create a range, block, document, or screenshot review thread.

Create a range, block, document, or screenshot review thread. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:comment
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCommentAdd.v1 — Create a range, block, document, or screenshot review thread..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comment add --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comment reply`#

Reply to a Content review thread.

Reply to a Content review thread. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:comment
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCommentReply.v1 — Reply to a Content review thread..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comment reply --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comment resolve`#

Resolve a Content review thread.

Resolve a Content review thread. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:comment
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCommentResolve.v1 — Resolve a Content review thread..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comment resolve --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comment assign`#

Assign a review thread to an explicitly granted agent.

Assign a review thread to an explicitly granted agent. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCommentAssign.v1 — Assign a review thread to an explicitly granted agent..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comment assign --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content publish`#

Atomically select a Content publication release.

Atomically select a Content publication release. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:publish
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentPublish.v1 — Atomically select a Content publication release..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content publish --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content release status`#

List Content publication releases.

List Content publication releases. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentReleaseStatus.v1 — List Content publication releases..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content release status --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content rollback`#

Move a publication pointer to a prior immutable release.

Move a publication pointer to a prior immutable release. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:publish
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentRollback.v1 — Move a publication pointer to a prior immutable release..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content rollback --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content grant`#

Grant a service principal a Content publication role.

Grant a service principal a Content publication role. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentGrant.v1 — Grant a service principal a Content publication role..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content grant --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content inspect`#

Inspect a Markdown file before Content import.

Inspect a Markdown file before Content import. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentInspect.v1 — Inspect a Markdown file before Content import..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content inspect --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content import`#

Import one file or a Markdown/MDX directory as immutable Content drafts.

Import one file or a Markdown/MDX directory as immutable Content drafts. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentImport.v1 — Import one file or a Markdown/MDX directory as immutable Content drafts..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url, --file, --dir, --base-revision

Examples:

sf content import --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`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:

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:

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:

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:

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:

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:

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:

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:

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:

sf diagnose ingest_id --watch --json

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 serialized production merge queue.

Validates with the workflow registered from base main, then advances main with a ref compare-and-swap. Each affected project is built independently from the merged main SHA.

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.v1 — Merge request identity and queue state.
Exit codes: 0, 10, 12, 64
Arguments: sha
Flags: --json, --jsonl, --base-url, --ref, --repo, --pr, --yes

Examples:

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 merge or production-deployment state.

Returns a serialized merge request for repository readers, or per-project production deployments for site operators.

Access: repo:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.release.status.v1 — Merge request or project deployment and receipt state.
Exit codes: 0, 10, 11
Arguments: id?
Flags: --json, --jsonl, --base-url, --repo

Examples:

sf release status 6f35983d-9ab3-4f16-a65c-6da3781984c7 --repo swyx/forge --json

sf release status --json

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

`sf release watch`#

Watch one merge or project deployment until terminal.

Polls only the merge or production-deployment status API with bounded exponential backoff and 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.v1 — Terminal merge or production-deployment status.
Exit codes: 0, 10, 11, 14, 64
Arguments: id
Flags: --json, --jsonl, --base-url, --repo, --timeout

Examples:

sf release watch 6f35983d-9ab3-4f16-a65c-6da3781984c7 --repo swyx/forge --json

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

`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:

sf deploy check

sf deploy check --json

Remediation: Fix the cited forgeBuild.ts constraint.

`sf observe install`#

Install the local skill observability collector.

Installs the pinned macOS OTel Collector, a metadata-only Claude Code activation hook, local event export, and optional vendor-neutral fan-out.

Access: skit:write
Safety: mutating; Configuration writes are deterministic and hooks are deduplicated.
Confirmation: Requires --yes outside a TTY.
Output: forge.observe.install.v1 — Collector, adapter, privacy, and destination status.
Exit codes: 0, 12, 64, 65
Flags: --json, --jsonl, --base-url, --yes, --metadata-only, --forge, --otlp-endpoint, --local-file, --without-git-ai, --without-service, --collector-binary, --claude-settings, --launchd-plist, --home

Examples:

sf observe install --metadata-only --forge --yes

sf observe install --otlp-endpoint https://api.honeycomb.io --yes

Remediation: Run sf observe doctor --json.

`sf observe status`#

Status the local skill observability collector.

Status the local metadata-only OTel installation without deleting retained evidence.

Access: none
Safety: read-only; Configuration writes are deterministic and hooks are deduplicated.
Confirmation: Never prompts.
Output: forge.observe.status.v1 — Collector, adapter, privacy, and destination status.
Exit codes: 0, 12, 64, 65
Flags: --json, --jsonl, --base-url, --yes, --metadata-only, --forge, --otlp-endpoint, --local-file, --without-git-ai, --without-service, --collector-binary, --claude-settings, --launchd-plist, --home

Examples:

sf observe status --json

Remediation: Run sf observe doctor --json.

`sf observe doctor`#

Doctor the local skill observability collector.

Doctor the local metadata-only OTel installation without deleting retained evidence.

Access: none
Safety: read-only; Configuration writes are deterministic and hooks are deduplicated.
Confirmation: Never prompts.
Output: forge.observe.doctor.v1 — Collector, adapter, privacy, and destination status.
Exit codes: 0, 12, 64, 65
Flags: --json, --jsonl, --base-url, --yes, --metadata-only, --forge, --otlp-endpoint, --local-file, --without-git-ai, --without-service, --collector-binary, --claude-settings, --launchd-plist, --home

Examples:

sf observe doctor --json

Remediation: Run sf observe doctor --json.

`sf observe uninstall`#

Uninstall the local skill observability collector.

Uninstall the local metadata-only OTel installation without deleting retained evidence.

Access: none
Safety: mutating; Configuration writes are deterministic and hooks are deduplicated.
Confirmation: Requires --yes outside a TTY.
Output: forge.observe.uninstall.v1 — Collector, adapter, privacy, and destination status.
Exit codes: 0, 12, 64, 65
Flags: --json, --jsonl, --base-url, --yes, --metadata-only, --forge, --otlp-endpoint, --local-file, --without-git-ai, --without-service, --collector-binary, --claude-settings, --launchd-plist, --home

Examples:

sf observe uninstall --json

Remediation: Run sf observe doctor --json.

`sf add skit`#

Install a complete SKIT release.

Resolves a Forge ID, clone URL, direct URL/archive, or local path into the content-addressed library and atomically projects enabled children to supported agents. Standalone skit add and skit install use this same handler.

Aliases: sf skit install, sf skit add.

Access: none
Safety: mutating; Idempotent by SKIT release digest and agent projection.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.install.v1 — Exact installation and per-child state.
Exit codes: 0, 12, 64, 65
Arguments: source
Flags: --json, --jsonl, --base-url, --version, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root

Examples:

sf add skit owner/name --version 1.0.0

skit add https://example.test/skills.git

Remediation: Run skit doctor and resolve conflicts explicitly.

`sf skit init`#

Create a single-skill SKIT scaffold.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.init.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit init

skit init

Remediation: Run skit doctor --json.

`sf skit validate`#

Validate bundle declarations, files, hashes, and static audit.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.validate.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit validate

skit validate

Remediation: Run skit doctor --json.

`sf skit publish`#

Publish the current valid draft as an immutable release.

Access: skit:write
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.publish.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit publish

skit publish

Remediation: Run skit doctor --json.

`sf skit pull`#

Resolve and install a SKIT source.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.pull.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit pull

skit pull

Remediation: Run skit doctor --json.

`sf skit enable`#

Enable and project one contained skill.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.enable.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: skill-or-path
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit enable

skit enable

Remediation: Run skit doctor --json.

`sf skit disable`#

Disable one contained skill without altering its bundle.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.disable.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: skill-or-path
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit disable

skit disable

Remediation: Run skit doctor --json.

`sf skit update`#

Update one or all installed SKITs from recorded sources.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.update.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit update

skit update

Remediation: Run skit doctor --json.

`sf skit remove`#

Remove clean managed projections and local desired state.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.remove.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit remove

skit remove

Remediation: Run skit doctor --json.

`sf skit list`#

List Forge-managed local SKIT installations.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.list.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit list

skit list

Remediation: Run skit doctor --json.

`sf skit sync`#

Validate and three-way reconcile a bound editable draft.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.sync.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit sync

skit sync

Remediation: Run skit doctor --json.

`sf skit inventory`#

Rescan known agent roots without changing projections.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.inventory.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit inventory

skit inventory

Remediation: Run skit doctor --json.

`sf skit reconcile`#

Apply only safe non-conflicting desired-state changes.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.reconcile.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit reconcile

skit reconcile

Remediation: Run skit doctor --json.

`sf skit doctor`#

Diagnose local library, adapter, and projection state.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.doctor.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit doctor

skit doctor

Remediation: Run skit doctor --json.

`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:

sf benchmark swyxkit --json

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`#

Registers a Forge account and stores the resulting full-access session in protected OS storage by default. If protected storage is unavailable, the command fails closed; use --storage file only for an explicit local sandbox or coding-agent copy.

Access: none
Safety: mutating; Account creation is not automatically idempotent; retry only when it is clear registration did not succeed.
Confirmation: Validates username, email, and selected storage before reading a password.
Output: forge.auth.register.v1 — Sanitized registered identity and selected credential storage.
Exit codes: 0, 10, 64
Flags: --json, --jsonl, --base-url, --username, --email, --password, --invite-code, --storage

Examples:

sf register --username NAME --email ADDRESS --invite-code CODE

sf register --username NAME --email ADDRESS --storage file

Remediation: If protected storage is unavailable, deliberately make a sandbox-readable local copy with sf register --username NAME --email ADDRESS --storage file.

`sf repo create`#

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:

sf repo create

Remediation: Run sf help for the current arguments.

`sf repo list`#

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:

sf repo list

Remediation: Run sf help for the current arguments.

`sf repo get`#

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:

sf repo get

Remediation: Run sf help for the current arguments.

`sf repo update`#

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:

sf repo update

Remediation: Run sf help for the current arguments.

`sf repo star`#

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:

sf repo star

Remediation: Run sf help for the current arguments.

`sf repo unstar`#

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:

sf repo unstar

Remediation: Run sf help for the current arguments.

`sf repo import`#

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:

sf repo import

Remediation: Run sf help for the current arguments.

`sf clone-url`#

Print a clone URL.

Returns the canonical HTTPS clone URL for one Forge repository.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.clone-url.v1 — Canonical repository clone URL.
Exit codes: 0, 64
Arguments: owner/repo
Flags: --json, --jsonl, --base-url

Examples:

sf clone-url owner/repo

sf clone-url owner/repo --json

Remediation: Pass a repository in owner/repo form.

`sf transcript upload`#

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:

sf transcript upload

Remediation: Run sf help for the current arguments.

`sf hooks install`#

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:

sf hooks install

Remediation: Run sf help for the current arguments.

`sf hooks status`#

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:

sf hooks status

Remediation: Run sf help for the current arguments.

`sf migrate`#

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:

sf migrate

Remediation: Run sf help for the current arguments.

`sf llms`#

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:

sf llms

Remediation: Run sf help for the current arguments.

Opening the page…

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.

Quick start#

Forge CLI is the headless interface for coding agents and the concise command line for humans who submit serialized merges and observe exact-SHA production attempts.

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.

Authenticate: sf auth login — Create or refresh this machine’s Forge session in protected OS storage without printing its credential.
Inspect a release: sf release status — Read the serialized merge and its latest exact-SHA production attempt.
Wait without mutating: sf release watch — Watch one attempt until terminal. This never pushes, retries, activates, or rolls back.
Diagnose before repair: 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 successful exact-SHA attempt with its compact receipt proves a platform release is deployed.
Headless by default: JSON and JSONL are stable contracts; progress and failures are machine-actionable.
Explicit credential boundary: normal sessions use protected OS storage, while Git uses separate repository-scoped credentials.
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 — Describe a command or the complete CLI.
sf commands — List command paths for machine discovery.
sf schema — Print the versioned CLI command manifest.
sf docs generate — Generate CLI reference artifacts from the registry.

Authentication#

sf auth status — Show the active credential without exposing it.
sf auth login — Authenticate a Forge CLI session.
sf auth bridge — Copy a protected Forge session to explicit sandbox file storage.
sf auth git-credential — Prepare repository-scoped credentials for Git.
sf auth logout — Remove this machine’s stored Forge credentials.
sf auth revoke — Revoke a personal access token.
sf whoami — Return the authenticated Forge identity.
sf scopes — Show the active credential scopes.
sf register — Register a Forge account.

Repository state and Git#

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

Actions#

sf actions list — List Actions runs.
sf actions inspect — Inspect an Action run and linked release receipt.
sf actions cancel — Cancel an Action run.

Other workflows#

sf agent profiles — List repository-agent execution profiles.
sf agent list — List durable repository-agent threads.
sf agent create — Create or recover a durable repository-agent thread.
sf agent view — Inspect one durable repository-agent thread.
sf agent message — Message a repository agent at an explicit execution tier.
sf agent events — Read normalized repository-agent events after a cursor.
sf agent cancel — Cancel one repository-agent run.
sf agent approve — Resolve one repository-agent approval.
sf content create — Create an account or repository Content publication.
sf content attach — Move an existing publication into a repository scope.
sf content list — List an editorial publication and its draft documents.
sf content get — Read one published Content document.
sf content draft — Create an immutable Content draft revision.
sf content draft pull — Fetch the selected Content draft for local or agent work.
sf content draft push — Push an immutable Content draft revision.
sf content draft diff — Diff two immutable Content revisions.
sf content draft preview — Preview the selected Content draft safely.
sf content history — List immutable revisions for a Content document.
sf content comments — List Content review threads.
sf content comment add — Create a range, block, document, or screenshot review thread.
sf content comment reply — Reply to a Content review thread.
sf content comment resolve — Resolve a Content review thread.
sf content comment assign — Assign a review thread to an explicitly granted agent.
sf content publish — Atomically select a Content publication release.
sf content release status — List Content publication releases.
sf content rollback — Move a publication pointer to a prior immutable release.
sf content grant — Grant a service principal a Content publication role.
sf content inspect — Inspect a Markdown file before Content import.
sf content import — Import one file or a Markdown/MDX directory as immutable Content drafts.
sf release enqueue — Submit an exact feature SHA to the serialized production merge queue.
sf release status — Read canonical merge or production-deployment state.
sf release watch — Watch one merge or project deployment until terminal.
sf observe install — Install the local skill observability collector.
sf observe status — Status the local skill observability collector.
sf observe doctor — Doctor the local skill observability collector.
sf observe uninstall — Uninstall the local skill observability collector.
sf add skit — Install a complete SKIT release.
sf skit init — Create a single-skill SKIT scaffold.
sf skit validate — Validate bundle declarations, files, hashes, and static audit.
sf skit publish — Publish the current valid draft as an immutable release.
sf skit pull — Resolve and install a SKIT source.
sf skit enable — Enable and project one contained skill.
sf skit disable — Disable one contained skill without altering its bundle.
sf skit update — Update one or all installed SKITs from recorded sources.
sf skit remove — Remove clean managed projections and local desired state.
sf skit list — List Forge-managed local SKIT installations.
sf skit sync — Validate and three-way reconcile a bound editable draft.
sf skit inventory — Rescan known agent roots without changing projections.
sf skit reconcile — Apply only safe non-conflicting desired-state changes.
sf skit doctor — Diagnose local library, adapter, and projection state.
sf benchmark — Plan or run an exact-tree Forge/GitHub benchmark.
sf transcript upload — Upload an agent transcript.
sf hooks install — Install repository hooks.
sf hooks status — Inspect repository hooks.
sf llms — Fetch llms.txt.

Pull requests#

sf pr list — List pull requests.
sf pr view — Inspect a pull request.
sf pr create — Create a pull request.

Deploy#

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

Diagnostics#

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:

sf help status

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:

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:

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:

sf docs generate

sf docs generate --check

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

`sf auth status`#

Show the active credential without exposing it.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.auth.status.v1 — Sanitized API identity plus separate repository Git-wiring state.
Exit codes: 0, 10, 64
Arguments: owner/repo?
Flags: --json, --jsonl, --base-url

Examples:

sf auth status --json

sf auth status owner/repo --json

Remediation: Run sf auth login or set a short-lived SMOLFORGE_TOKEN. To inspect Git access explicitly, run sf auth status owner/repo.

`sf auth login`#

Authenticate a Forge CLI session.

Aliases: sf login.

Access: none
Safety: mutating; Creates or replaces the selected local login session. Durable mode replaces the prior CLI-managed global Git credential.
Confirmation: Durable global Git access requires the exact scope/expiry flags plus --yes; validation and confirmation happen before password input or remote mutation.
Output: forge.auth.login.v1 — Sanitized authenticated identity, selected login storage, and Git credential mode; never either bearer.
Exit codes: 0, 10, 64
Flags: --json, --jsonl, --base-url, --username, --email, --storage, --git-scope, --expires, --yes

Examples:

sf auth login

sf auth login --username alice

sf auth login --storage file

sf auth login --git-scope global --expires never --yes

Remediation: Use ordinary login for least privilege, or review and explicitly run sf auth login --git-scope global --expires never --yes on a trusted durable machine.

`sf auth bridge`#

Copy a protected Forge session to explicit sandbox file storage.

Access: none
Safety: mutating; Replaces only the explicit file copy for the selected Forge origin.
Confirmation: Never prompts. Running this command is explicit consent to make the full-access session readable by a local sandbox or coding agent.
Output: forge.auth.bridge.v1 — Sanitized sandbox credential-file path and session-expiry metadata; never the bearer.
Exit codes: 0, 10, 64
Flags: --json, --jsonl, --base-url

Examples:

sf auth bridge

Remediation: Run sf auth login to create a protected host session, then retry sf auth bridge.

`sf auth git-credential`#

Prepare repository-scoped credentials for Git.

Access: repo:read, repo:write
Safety: mutating; Reuses a valid repository credential. When the helper and scoped credential are already configured, it performs no Git-config write or token mint.
Confirmation: Never prompts. Validates repository resolution and selected credential storage before changing Git configuration or minting a repository token.
Output: forge.auth.git-credential.v1 — Sanitized repository source, helper/configuration state, storage, and credential-expiry metadata; never the bearer.
Exit codes: 0, 10, 11, 64
Arguments: owner/repo?
Flags: --json, --jsonl, --base-url, --storage

Examples:

sf auth git-credential owner/repo

sf auth git-credential

sf auth git-credential owner/repo --storage file --json

Remediation: Run sf auth login, then retry with sf auth git-credential owner/repo. In a local sandbox without protected storage, deliberately use --storage file.

`sf auth logout`#

Remove this machine’s stored Forge credentials.

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

Examples:

sf auth logout --json

`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:

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:

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:

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:

sf git doctor --json

Remediation: Run sf auth login, then sf auth git-credential owner/repo, and retry.

`sf actions list`#

List Actions runs.

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, 64
Arguments: owner/repo?
Flags: --json, --jsonl, --base-url, --limit, --status, --branch

Examples:

sf actions list --json

sf actions list owner/repo --branch codex/repo-rename-redirect --json

Remediation: Use --branch with one exact branch, or 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:

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:

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:

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:

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:

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:

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:

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

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:

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:

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:

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 content create`#

Create an account or repository Content publication.

Create an account or repository Content publication. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCreate.v1 — Create an account or repository Content publication..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url, --repo, --org, --title, --description, --visibility

Examples:

sf content create --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content attach`#

Move an existing publication into a repository scope.

Move an existing publication into a repository scope. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentAttach.v1 — Move an existing publication into a repository scope..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url, --repo, --slug

Examples:

sf content attach --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content list`#

List an editorial publication and its draft documents.

List an editorial publication and its draft documents. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentList.v1 — List an editorial publication and its draft documents..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content list --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content get`#

Read one published Content document.

Read one published Content document. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentGet.v1 — Read one published Content document..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content get --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft`#

Create an immutable Content draft revision.

Create an immutable Content draft revision. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentDraft.v1 — Create an immutable Content draft revision..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url, --slug, --title, --file, --metadata, --base-revision, --description, --collection

Examples:

sf content draft --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft pull`#

Fetch the selected Content draft for local or agent work.

Fetch the selected Content draft for local or agent work. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentDraftPull.v1 — Fetch the selected Content draft for local or agent work..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content draft pull --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft push`#

Push an immutable Content draft revision.

Push an immutable Content draft revision. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentDraft.v1 — Push an immutable Content draft revision..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content draft push --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft diff`#

Diff two immutable Content revisions.

Diff two immutable Content revisions. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentDraftDiff.v1 — Diff two immutable Content revisions..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content draft diff --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content draft preview`#

Preview the selected Content draft safely.

Preview the selected Content draft safely. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentDraftPreview.v1 — Preview the selected Content draft safely..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content draft preview --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content history`#

List immutable revisions for a Content document.

List immutable revisions for a Content document. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentHistory.v1 — List immutable revisions for a Content document..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content history --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comments`#

List Content review threads.

List Content review threads. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentComments.v1 — List Content review threads..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comments --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comment add`#

Create a range, block, document, or screenshot review thread.

Create a range, block, document, or screenshot review thread. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:comment
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCommentAdd.v1 — Create a range, block, document, or screenshot review thread..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comment add --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comment reply`#

Reply to a Content review thread.

Reply to a Content review thread. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:comment
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCommentReply.v1 — Reply to a Content review thread..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comment reply --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comment resolve`#

Resolve a Content review thread.

Resolve a Content review thread. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:comment
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCommentResolve.v1 — Resolve a Content review thread..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comment resolve --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content comment assign`#

Assign a review thread to an explicitly granted agent.

Assign a review thread to an explicitly granted agent. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentCommentAssign.v1 — Assign a review thread to an explicitly granted agent..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content comment assign --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content publish`#

Atomically select a Content publication release.

Atomically select a Content publication release. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:publish
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentPublish.v1 — Atomically select a Content publication release..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content publish --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content release status`#

List Content publication releases.

List Content publication releases. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentReleaseStatus.v1 — List Content publication releases..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content release status --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content rollback`#

Move a publication pointer to a prior immutable release.

Move a publication pointer to a prior immutable release. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:publish
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentRollback.v1 — Move a publication pointer to a prior immutable release..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content rollback --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content grant`#

Grant a service principal a Content publication role.

Grant a service principal a Content publication role. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentGrant.v1 — Grant a service principal a Content publication role..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content grant --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content inspect`#

Inspect a Markdown file before Content import.

Inspect a Markdown file before Content import. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.content.contentInspect.v1 — Inspect a Markdown file before Content import..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url

Examples:

sf content inspect --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`sf content import`#

Import one file or a Markdown/MDX directory as immutable Content drafts.

Import one file or a Markdown/MDX directory as immutable Content drafts. This operates on Forge Content documents and releases, never Git branches or application deployments.

Access: content:write
Safety: mutating; Use the returned revision or release identity when retrying.
Confirmation: Never prompts.
Output: forge.content.contentImport.v1 — Import one file or a Markdown/MDX directory as immutable Content drafts..
Exit codes: 0, 10, 11, 12, 64
Flags: --json, --jsonl, --base-url, --file, --dir, --base-revision

Examples:

sf content import --json

Remediation: Inspect the publication state and retry with the current Content revision or release identity.

`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:

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:

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:

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:

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:

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:

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:

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:

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.

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:

sf diagnose ingest_id --watch --json

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 serialized production merge queue.

Validates with the workflow registered from base main, then advances main with a ref compare-and-swap. Each affected project is built independently from the merged main SHA.

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.v1 — Merge request identity and queue state.
Exit codes: 0, 10, 12, 64
Arguments: sha
Flags: --json, --jsonl, --base-url, --ref, --repo, --pr, --yes

Examples:

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 merge or production-deployment state.

Returns a serialized merge request for repository readers, or per-project production deployments for site operators.

Access: repo:read
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.release.status.v1 — Merge request or project deployment and receipt state.
Exit codes: 0, 10, 11
Arguments: id?
Flags: --json, --jsonl, --base-url, --repo

Examples:

sf release status 6f35983d-9ab3-4f16-a65c-6da3781984c7 --repo swyx/forge --json

sf release status --json

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

`sf release watch`#

Watch one merge or project deployment until terminal.

Polls only the merge or production-deployment status API with bounded exponential backoff and 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.v1 — Terminal merge or production-deployment status.
Exit codes: 0, 10, 11, 14, 64
Arguments: id
Flags: --json, --jsonl, --base-url, --repo, --timeout

Examples:

sf release watch 6f35983d-9ab3-4f16-a65c-6da3781984c7 --repo swyx/forge --json

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

`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:

sf deploy check

sf deploy check --json

Remediation: Fix the cited forgeBuild.ts constraint.

`sf observe install`#

Install the local skill observability collector.

Installs the pinned macOS OTel Collector, a metadata-only Claude Code activation hook, local event export, and optional vendor-neutral fan-out.

Access: skit:write
Safety: mutating; Configuration writes are deterministic and hooks are deduplicated.
Confirmation: Requires --yes outside a TTY.
Output: forge.observe.install.v1 — Collector, adapter, privacy, and destination status.
Exit codes: 0, 12, 64, 65
Flags: --json, --jsonl, --base-url, --yes, --metadata-only, --forge, --otlp-endpoint, --local-file, --without-git-ai, --without-service, --collector-binary, --claude-settings, --launchd-plist, --home

Examples:

sf observe install --metadata-only --forge --yes

sf observe install --otlp-endpoint https://api.honeycomb.io --yes

Remediation: Run sf observe doctor --json.

`sf observe status`#

Status the local skill observability collector.

Status the local metadata-only OTel installation without deleting retained evidence.

Access: none
Safety: read-only; Configuration writes are deterministic and hooks are deduplicated.
Confirmation: Never prompts.
Output: forge.observe.status.v1 — Collector, adapter, privacy, and destination status.
Exit codes: 0, 12, 64, 65
Flags: --json, --jsonl, --base-url, --yes, --metadata-only, --forge, --otlp-endpoint, --local-file, --without-git-ai, --without-service, --collector-binary, --claude-settings, --launchd-plist, --home

Examples:

sf observe status --json

Remediation: Run sf observe doctor --json.

`sf observe doctor`#

Doctor the local skill observability collector.

Doctor the local metadata-only OTel installation without deleting retained evidence.

Access: none
Safety: read-only; Configuration writes are deterministic and hooks are deduplicated.
Confirmation: Never prompts.
Output: forge.observe.doctor.v1 — Collector, adapter, privacy, and destination status.
Exit codes: 0, 12, 64, 65
Flags: --json, --jsonl, --base-url, --yes, --metadata-only, --forge, --otlp-endpoint, --local-file, --without-git-ai, --without-service, --collector-binary, --claude-settings, --launchd-plist, --home

Examples:

sf observe doctor --json

Remediation: Run sf observe doctor --json.

`sf observe uninstall`#

Uninstall the local skill observability collector.

Uninstall the local metadata-only OTel installation without deleting retained evidence.

Access: none
Safety: mutating; Configuration writes are deterministic and hooks are deduplicated.
Confirmation: Requires --yes outside a TTY.
Output: forge.observe.uninstall.v1 — Collector, adapter, privacy, and destination status.
Exit codes: 0, 12, 64, 65
Flags: --json, --jsonl, --base-url, --yes, --metadata-only, --forge, --otlp-endpoint, --local-file, --without-git-ai, --without-service, --collector-binary, --claude-settings, --launchd-plist, --home

Examples:

sf observe uninstall --json

Remediation: Run sf observe doctor --json.

`sf add skit`#

Install a complete SKIT release.

Aliases: sf skit install, sf skit add.

Access: none
Safety: mutating; Idempotent by SKIT release digest and agent projection.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.install.v1 — Exact installation and per-child state.
Exit codes: 0, 12, 64, 65
Arguments: source
Flags: --json, --jsonl, --base-url, --version, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root

Examples:

sf add skit owner/name --version 1.0.0

skit add https://example.test/skills.git

Remediation: Run skit doctor and resolve conflicts explicitly.

`sf skit init`#

Create a single-skill SKIT scaffold.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.init.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit init

skit init

Remediation: Run skit doctor --json.

`sf skit validate`#

Validate bundle declarations, files, hashes, and static audit.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.validate.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit validate

skit validate

Remediation: Run skit doctor --json.

`sf skit publish`#

Publish the current valid draft as an immutable release.

Access: skit:write
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.publish.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit publish

skit publish

Remediation: Run skit doctor --json.

`sf skit pull`#

Resolve and install a SKIT source.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.pull.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit pull

skit pull

Remediation: Run skit doctor --json.

`sf skit enable`#

Enable and project one contained skill.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.enable.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: skill-or-path
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit enable

skit enable

Remediation: Run skit doctor --json.

`sf skit disable`#

Disable one contained skill without altering its bundle.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.disable.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: skill-or-path
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit disable

skit disable

Remediation: Run skit doctor --json.

`sf skit update`#

Update one or all installed SKITs from recorded sources.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.update.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit update

skit update

Remediation: Run skit doctor --json.

`sf skit remove`#

Remove clean managed projections and local desired state.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.remove.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit remove

skit remove

Remediation: Run skit doctor --json.

`sf skit list`#

List Forge-managed local SKIT installations.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.list.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit list

skit list

Remediation: Run skit doctor --json.

`sf skit sync`#

Validate and three-way reconcile a bound editable draft.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.sync.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Arguments: source-or-path?
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit sync

skit sync

Remediation: Run skit doctor --json.

`sf skit inventory`#

Rescan known agent roots without changing projections.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.inventory.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit inventory

skit inventory

Remediation: Run skit doctor --json.

`sf skit reconcile`#

Apply only safe non-conflicting desired-state changes.

Access: none
Safety: mutating; Fenced by exact hashes and preservation-first conflict checks.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.reconcile.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit reconcile

skit reconcile

Remediation: Run skit doctor --json.

`sf skit doctor`#

Diagnose local library, adapter, and projection state.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never overwrites unknown or externally modified files.
Output: forge.skit.doctor.v1 — SKIT package-management result.
Exit codes: 0, 11, 12, 64, 65
Flags: --json, --jsonl, --base-url, --version, --revision, --agent, --home, --claude-root, --codex-root, --opencode-root, --devin-root, --apply

Examples:

sf skit doctor

skit doctor

Remediation: Run skit doctor --json.

`sf benchmark`#

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

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:

sf benchmark swyxkit --json

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`#

Access: none
Safety: mutating; Account creation is not automatically idempotent; retry only when it is clear registration did not succeed.
Confirmation: Validates username, email, and selected storage before reading a password.
Output: forge.auth.register.v1 — Sanitized registered identity and selected credential storage.
Exit codes: 0, 10, 64
Flags: --json, --jsonl, --base-url, --username, --email, --password, --invite-code, --storage

Examples:

sf register --username NAME --email ADDRESS --invite-code CODE

sf register --username NAME --email ADDRESS --storage file

Remediation: If protected storage is unavailable, deliberately make a sandbox-readable local copy with sf register --username NAME --email ADDRESS --storage file.

`sf repo create`#

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:

sf repo create

Remediation: Run sf help for the current arguments.

`sf repo list`#

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:

sf repo list

Remediation: Run sf help for the current arguments.

`sf repo get`#

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:

sf repo get

Remediation: Run sf help for the current arguments.

`sf repo update`#

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:

sf repo update

Remediation: Run sf help for the current arguments.

`sf repo star`#

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:

sf repo star

Remediation: Run sf help for the current arguments.

`sf repo unstar`#

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:

sf repo unstar

Remediation: Run sf help for the current arguments.

`sf repo import`#

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:

sf repo import

Remediation: Run sf help for the current arguments.

`sf clone-url`#

Print a clone URL.

Returns the canonical HTTPS clone URL for one Forge repository.

Access: none
Safety: read-only; Safe to retry.
Confirmation: Never prompts.
Output: forge.clone-url.v1 — Canonical repository clone URL.
Exit codes: 0, 64
Arguments: owner/repo
Flags: --json, --jsonl, --base-url

Examples:

sf clone-url owner/repo

sf clone-url owner/repo --json

Remediation: Pass a repository in owner/repo form.

`sf transcript upload`#

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:

sf transcript upload

Remediation: Run sf help for the current arguments.

`sf hooks install`#

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:

sf hooks install

Remediation: Run sf help for the current arguments.

`sf hooks status`#

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:

sf hooks status

Remediation: Run sf help for the current arguments.

`sf migrate`#

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:

sf migrate

Remediation: Run sf help for the current arguments.

`sf llms`#

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:

sf llms

Remediation: Run sf help for the current arguments.

Forge CLI#

Quick start#

Design goals#

Jump to a command#

Discover and document#

Authentication#

Repository state and Git#

Actions#

Other workflows#

Pull requests#

Deploy#

Diagnostics#

Command reference#

sf help#

sf commands#

sf schema#

sf docs generate#

sf auth status#

sf auth login#

sf auth bridge#

sf auth git-credential#

sf auth logout#

sf auth revoke#

sf whoami#

sf scopes#

sf git doctor#

sf actions list#

sf actions inspect#

sf actions cancel#

sf agent profiles#

sf agent list#

sf agent create#

sf agent view#

sf agent message#

sf agent events#

sf agent cancel#

sf agent approve#

sf content create#

sf content attach#

sf content list#

sf content get#

sf content draft#

sf content draft pull#

sf content draft push#

sf content draft diff#

sf content draft preview#

sf content history#

sf content comments#

sf content comment add#

sf content comment reply#

sf content comment resolve#

sf content comment assign#

sf content publish#

sf content release status#

sf content rollback#

sf content grant#

sf content inspect#

sf content import#

sf pr list#

sf pr view#

sf pr create#

sf deploy list#

sf deploy status#

sf deploy retry#

sf deploy promote#

sf deploy rollback#

sf diagnose#

sf release enqueue#

sf release status#

sf release watch#

sf deploy check#

sf observe install#

sf observe status#

sf observe doctor#

sf observe uninstall#

sf add skit#

sf skit init#

sf skit validate#

sf skit publish#

sf skit pull#

`sf help`#

`sf commands`#

`sf schema`#

`sf docs generate`#

`sf auth status`#

`sf auth login`#

`sf auth bridge`#

`sf auth git-credential`#

`sf auth logout`#

`sf auth revoke`#

`sf whoami`#

`sf scopes`#

`sf git doctor`#

`sf actions list`#

`sf actions inspect`#

`sf actions cancel`#

`sf agent profiles`#

`sf agent list`#

`sf agent create`#

`sf agent view`#

`sf agent message`#

`sf agent events`#

`sf agent cancel`#

`sf agent approve`#

`sf content create`#

`sf content attach`#

`sf content list`#

`sf content get`#

`sf content draft`#

`sf content draft pull`#

`sf content draft push`#

`sf content draft diff`#

`sf content draft preview`#

`sf content history`#

`sf content comments`#

`sf content comment add`#

`sf content comment reply`#

`sf content comment resolve`#

`sf content comment assign`#

`sf content publish`#

`sf content release status`#

`sf content rollback`#

`sf content grant`#

`sf content inspect`#

`sf content import`#

`sf pr list`#

`sf pr view`#

`sf pr create`#

`sf deploy list`#

`sf deploy status`#

`sf deploy retry`#

`sf deploy promote`#

`sf deploy rollback`#

`sf diagnose`#

`sf release enqueue`#

`sf release status`#

`sf release watch`#

`sf deploy check`#

`sf observe install`#

`sf observe status`#

`sf observe doctor`#

`sf observe uninstall`#

`sf add skit`#

`sf skit init`#

`sf skit validate`#

`sf skit publish`#

`sf skit pull`#

`sf skit enable`#

`sf skit disable`#

`sf skit update`#

`sf skit remove`#

`sf skit list`#

`sf skit sync`#

`sf skit inventory`#

`sf skit reconcile`#

`sf skit doctor`#

`sf benchmark`#

`sf register`#

`sf repo create`#

`sf repo list`#