@smolai/forge

Forge’s headless CLI for coding agents. It installs both smolforge and sf.

Preview: password/session and personal-access-token authentication are available. Browser PKCE/device authorization and audited operator credentials are not shipped yet, and operator commands fail closed.

npm install -g @smolai/forge
sf commands --json
sf help status

Authentication is capability-specific. sf auth status proves only the Forge API session; it does not claim that Git is ready. Select a repository when the operation needs Git:

sf auth status
sf auth status owner/repo --json
sf auth git-credential owner/repo

The repository check is read-only: it confirms server permission, local helper wiring, path-scoped lookup, and the stored repository credential without minting a token or rewriting Git configuration. The setup command is explicit, repository-scoped, and no-ops when that target is already ready.

Credential availability uses Git's credential fill/helper get operation with interactive prompting disabled. Forge does not call helper store or erase during status, though an independently installed credential helper may maintain its own access telemetry. Server verification may likewise update a credential's last-used timestamp; it does not create, replace, or broaden one. For a repository target, exit zero means the API session and Git-read capability are ready. Git-write permission is reported separately, so a legitimately read-only repository is not presented as a failed read check.

Forge API requests from the CLI send a stable smolforge/<version> user agent. Other API clients should send an identifying user agent for operability, but do not need to impersonate a browser. A network-edge rejection is reported separately from Forge 401, 403, 429, and retryable 5xx responses.

The canonical command reference and machine-readable manifest are generated from the typed command registry, not maintained here:

• docs/reference/cli.md
• docs/reference/cli.manifest.json

The npm package also includes those generated files under docs/reference/ so agents can inspect the exact command contract installed with the CLI.

Regenerate and verify documentation with:

sf docs generate
sf docs generate --check

Automation output and argument parsing

Use --json when a script needs exactly one final JSON object on stdout. Use --jsonl when it also needs structured progress events; every line is a JSON object and the final line is the result or error event. Human prose never leaks into either machine-readable stream.

The typed command registry also drives option parsing. Unknown options, missing option values, missing required arguments, and extra positional arguments fail before a command performs network or filesystem work. -h is equivalent to --help. Use -- to end option parsing when a positional path begins with a hyphen:

sf deploy check --json -- --literal-file-name

Session credential storage

sf auth login and sf register receive a full-access Forge session. By default, the CLI keeps it in protected OS credential storage instead of a plaintext file. The keychain spelling is the cross-platform flag name for that protected store.

| Platform | Default protected store | If it is unavailable or locked | | --- | --- | --- | | macOS | Keychain (security) | Login fails closed; no file is created. | | Linux | Secret Service/libsecret (secret-tool) | This includes headless or locked-keyring failures: login fails closed; no file is created. | | Windows | Credential Manager | Login fails closed; no file is created. |

Explicit flags always win:

# Require protected OS storage. This is the default when it is available.
sf auth login --storage keychain

# Deliberately make the session available to a local sandbox or coding agent.
sf auth login --storage file

--storage file writes ~/.smolforge/credentials.json. On macOS and Linux, the CLI creates a mode-0700 directory and mode-0600 file. Windows uses its user-profile ACLs instead of POSIX modes; this remains an explicit, less-protected sandbox/agent-readable copy. In every case, it is an explicit consent boundary: any process running as the user that can read the file can use the full Forge account session. Protected-store failures never silently downgrade to this file. When a deliberate file copy is needed on a machine without a usable protected store, retry with exactly sf auth login --storage file.

If the normal login is already in protected host storage and a sandbox needs it, use the explicit bridge instead:

sf auth bridge

The bridge copies the session to that same file path without changing the host’s normal storage choice. Its human output identifies the path, says that the copy grants full Forge account access, reports the recorded expiry, and explains cleanup. --json and --jsonl retain data-only, machine-readable output and never include the bearer.

Git and cleanup

A browser or CLI API session is not itself a Git credential. Before Forge Git pushes or pulls, prepare the repository-scoped credential and inspect both states:

sf auth git-credential owner/repo
sf auth status owner/repo

This installs only Forge’s URL-scoped Git credential helper and creates or reuses a short-lived repository credential. It does not expose the broad session, rewrite Git remotes, or replace unrelated credential helpers. Inside a checkout with exactly one unambiguous HTTPS Forge remote, the owner/repo argument may be omitted. Scripts and checkouts with multiple Forge remotes should always pass it explicitly. Use --storage keychain for the protected OS store or --storage file only when an agent-readable copy is deliberately required.

sf actions list supports an exact branch filter. Both a short branch name and its canonical refs/heads/ form select the same branch:

sf actions list owner/repo --branch codex/my-change
sf actions list owner/repo --branch refs/heads/codex/my-change --json

To remove local copies and the CLI-managed Git credentials, run:

sf auth logout

Logout removes local protected-store and explicit-file copies, and reports if it cannot confirm protected-store cleanup. It does not remotely revoke an already-copied broad Forge session. Dedicated revocable CLI and sandbox credentials are a planned follow-up; this release deliberately keeps the change limited to storage and consent boundaries.