Generating from the CLI

The CLI can run the full authoring loop from your terminal: generate candidates, review them in a focused browser page or from an agent, accept one into a canonical slot, publish an immutable release, and install that exact release locally.

Create a project API key

Open the project workspace, choose CLI access, and create an API key. Keys belong to one project and can be limited to these scopes:

• packs:read
• icons:generate
• packs:write
• packs:publish

The full secret is displayed once. Configure it locally:

icon-forge auth set --project acme/brand

The prompt does not echo the secret. The credential is stored in the platform config directory with user-only permissions on POSIX systems.

For agents and CI, inject the secret instead of storing it:

export ICONFORGE_TOKEN="ifk_..."

Treat API keys like passwords

Do not commit an API key or pass it as a command-line argument. Revoke a key from CLI access when an agent, machine, or CI environment no longer needs it.

Generate and review

icon-forge generate search \
  --pack acme/brand/core-icons \
  --prompt "a simple magnifying glass" \
  --style outline \
  --tier standard

The optional first argument is the future canonical slot name and import token. If you omit it, Icon Forge asks the configured naming model for a short canonical name and falls back to a deterministic slug if naming is unavailable. The resolved name is frozen before generation and is passed to the image model separately from the visual prompt.

In an interactive terminal, generate opens a focused review page as soon as the request is accepted. The page shows candidates as they finish. You can choose any ready candidate or reroll; a reroll is a new billable generation attempt under the same review URL. Once you choose, the waiting CLI publishes the exact canonical hash and installs that immutable release locally.

--style accepts a style name, preset slug, or style ID. Add up to four PNG, JPEG, or WebP reference images by repeating --ref:

icon-forge generate search \
  --pack acme/brand/core-icons \
  --prompt "match this product's search icon" \
  --style outline \
  --ref ./references/search.png \
  --ref ./references/navigation.png

The selected tier controls cost and candidate count. Generation alone does not change the canonical pack; only an explicit acceptance does.

Before submitting, the CLI saves the run and its idempotency key. If the process loses the response, crashes, or times out while candidates are still running, resume it without spending twice:

icon-forge generate --resume <run-id> --json

If iconforge.json contains exactly one pack, --pack can be omitted.

Agent-controlled selection

--json and --no-browser never open a browser or prompt. The CLI waits for the tier portfolio, caches available SVG, raster, and thumbnail assets in its platform cache directory, and returns their absolute paths. An agent can inspect those files, then select one by its 1-based number or exact draft ID:

icon-forge generate search \
  --pack acme/brand/core-icons \
  --prompt "a simple magnifying glass" \
  --style outline \
  --no-browser \
  --json

icon-forge accept <run-id> --candidate 2 --framework react --json

icon-forge accept <run-id> --draft <draft-id> --framework vue --json

By default, accept:

1. Verifies the draft is ready and belongs to the generation run and target pack
2. Creates or resolves the named canonical slot
3. Refuses to replace an occupied slot unless --replace is present
4. Refuses to include unrelated unpublished pack changes
5. Assigns the chosen draft
6. Publishes with a canonical compare-and-swap guard
7. Installs the exact release hash returned by publish
8. Creates or updates iconforge.json and iconforge-lock.json

The run record is resumable. If publish succeeds but local installation fails, rerun the same accept command; it reuses the recorded release instead of publishing again.

YOLO mode

For a fully autonomous agent flow, use --yolo:

icon-forge generate search \
  --pack acme/brand/core-icons \
  --prompt "a simple magnifying glass" \
  --style outline \
  --tier hd \
  --yolo \
  --framework react \
  --json

YOLO is a workflow preset, not a client-side guess. The backend’s best_single policy chooses one eligible model using the selected tier’s configured model quality scores, charges the tier’s explicit single-pick price, and generates exactly one candidate. The CLI accepts that candidate only if it is publish-ready, then uses the same atomic slot assignment, publish compare-and-swap, and exact-hash install path as a human choice. It never treats “candidate 1” from a portfolio as “best,” and a failed candidate does not silently spend credits on another attempt.

If local install configuration does not exist, pass --framework in non-interactive YOLO runs. Install preflight happens before generation so a missing local choice cannot waste a request.

Redo a canonical slot

Redo generates a replacement while keeping the current canonical icon live:

icon-forge redo search --pack acme/brand/core-icons

Icon Forge inherits the slot’s resolved prompt, style, tier, settings, and source lineage. Acceptance is guarded by the slot version captured when redo began, so it cannot overwrite a concurrent edit. Add --yolo for the autonomous single-candidate version.

Publish and install controls

Flag	Behavior
--replace	Replace an occupied slot for a normal generation
--include-dirty	Deliberately include other unpublished canonical changes in the release
--no-browser	Keep review in the terminal; never open or prompt
--yolo	Generate one backend-ranked candidate, accept, publish, and install
--no-install	Assign and publish without changing local files
--no-publish --no-install	Assign the candidate but leave the pack unpublished
--update-pin	Move an existing hash:... config pin to the new release
--framework react|vue|react-native	Initialize install config non-interactively
--output-dir PATH	Override the local install base directory
--force / --skip	Apply normal install conflict handling

If a pack is already pinned in iconforge.json, the CLI will not silently move it. Pass --update-pin or publish with --no-install.

Agent output

Pass --json to suppress progress logs and emit one machine-readable result. Errors are also emitted as structured JSON on stderr with a non-zero exit code.

Generation JSON includes:

• runId and the resumable run file
• pack, resolved slot, tier policy, and candidate metadata
• local thumbnail, raster, and SVG paths when available
• the exact next resume or acceptance command

Acceptance JSON includes:

• accepted draft and canonical slot IDs
• immutable release hash
• whether installation completed
• final local output directory

What “best” means

The public API calls the policy best_single, not “highest Elo.” Bundled models start with a dated external image-arena score, while unknown and custom models remain unrated until an admin scores them. Admin-managed quality scores are authoritative; tier weight and stable ordering break ties. That keeps the wire contract honest while allowing a learned internal rating system to replace the scoring implementation later.

For install-only usage, see Installing Packs. For config and lockfile behavior, see Config & Lockfile.