reference

The forge CLI, command by command

In discovery order, with a cheat sheet up front and a table of contents to jump straight to the point.

Commands appear in the order you meet them: install, sign in, write, test, publish, operate. The table of contents on the left jumps straight to a specific command.

Cheat sheet#

Command	Effect
`forge init`	Guided setup: workspace, sign-in, pull agents, install skill
`forge signup <email> --team <name>`	Creates your team, then signs you in
`forge login [email]` / `whoami` / `logout`	Magic-link session, identity, sign-out
`forge pull [slug]`	Deployment → files
`forge push <slug> [--activate]`	Files → deployment (mirror); `--activate` publishes
`forge diff <slug>`	What differs between local and deployed
`forge run <slug> --payload '<json>'`	Runs the agent
`forge tool <slug> <name> [--args '<json>']`	Runs one tool, no LLM
`forge bench <slug> [--case <name>]`	Replays the golden set
`forge verdict <slug> --case <name> --run <id> --passed\|--failed`	Records a judgement
`forge runs <slug>` / `trace <runId>` / `verdicts <slug>`	History, detailed trace, quality
`forge versions <slug>` / `pull <slug> --version <n>`	Timeline and rollback
`forge secret set <slug> NAME=VALUE`	Secret on the agent's worker
`forge keys create\|list\|revoke`	Tenant API keys
`forge status` / `llm set\|clear` / `credit add\|history`	Credit, BYOK keys, top-up
`forge invite <email>`	Invites a colleague to the team
`forge ui [--port N]`	Local admin interface
`forge update` / `kit update`	Updates the binary, then `lib/`

Install#

macOS and Linux, a single dependency-free binary:

curl -fsSL https://agent-forge.cc/download/forge-darwin-arm64 -o forge
chmod +x forge && sudo mv forge /usr/local/bin/

On macOS a .dmg installer is also available from the download page. forge update then upgrades the binary to the latest published release; forge kit update rewrites the workspace lib/ library accordingly.

Driving Forge from a coding agent#

This is the intended way to use Forge. forge init — or forge skill install on its own — drops into your workspace:

.claude/skills/forge/ and .claude/skills/agent-dev/ for Claude Code;
AGENTS.md at the root for Codex, which reads it natively;
a grounding CLAUDE.md if the workspace has none.

These files teach your assistant every command, the iteration methodology, the known pitfalls and the prompting principles specific to each model family. Concretely, you write "add a golden case for ambiguous queries and make the bench pass": the assistant creates the file, pushes, runs the bench, reads the traces and fixes.

Everything is reinstallable at will — forge skill install is idempotent and rewrites the skill after each binary update.

Create your team#

forge signup you@example.com --team your-team

Creates the tenant, then proceeds to sign-in. Without a prior invitation, the team starts on the free tier: discovery LLM credit and a monthly web-search quota.

Sign-in uses a magic link. A verification code appears in your terminal and must match the one on the page opened from the email — this is what protects against an intercepted or misdirected link. Sessions last 90 days.

forge whoami shows the current identity and tenant; forge logout revokes the session and wipes local credentials.

The workspace#

forge init

Safe to re-run: the command picks up where it stopped. It resolves the workspace, signs in if needed, pulls every team agent, installs the skill, and drops the lib/ library plus an example agent.

The workspace is the folder containing agents/. It resolves in this order: the FORGE_WORKSPACE variable, then an agents/ folder already present in the current directory, then ~/forge.

forge init also offers to initialise a git repository if there is none — strongly recommended: Forge versions what it executes, but the history of your sources remains git's job.

Write an agent#

forge push#

forge push my-agent
forge push my-agent --activate

Sends files to the deployment. The semantics are a mirror: a golden case deleted locally is deleted server-side. Files are always the complete reference.

If agent.json carries runtime: "worker", the CLI bundles agent.ts and the Cloudflare deployment is relayed by the control plane — the CLI never holds a Cloudflare token.

--activate publishes the agent. The rule of method: never activate without a green golden set.

forge pull, forge diff#

forge pull fetches the team's agents into files; forge pull <slug> fetches one. forge diff <slug> lists diverging fields and exits with code 1 when something differs — usable in a verification script.

Run#

forge run my-agent --payload '{"query":"..."}'

Execution is remote by default: it spends a real run, with real LLM cost, and it is traced. --local is reserved for development inside the source repository, with keys available locally.

forge tool#

forge tool my-agent --list
forge tool my-agent musicme_search --args '{"q":"..."}'

Runs a single tool, without calling the model: zero tokens spent. Secrets stay on the worker; your session is enough. It is the cheapest way to explore an API from the terminal and understand what the agent actually sees.

Test#

forge bench#

forge bench my-agent
forge bench my-agent --case ambiguous-query

Replays the golden set. Each case costs a real run — while fixing something, target a single case with --case rather than replaying everything.

forge trace, runs, verdicts#

forge runs <slug> lists recent runs with status, tokens, cost, latency and version. forge trace <runId> unfolds the full trace: LLM steps, tool calls, inputs and outputs, errors.

Two variants are invaluable during incident analysis: --version returns the complete state of the agent that produced the run, --prompt extracts the prompts alone.

forge verdict <slug> --case <name> --run <runId> --passed|--failed [--notes '…'] records the judgement, and forge verdicts <slug> gives the per-case history.

Version#

forge versions my-agent
forge pull my-agent --version 7

The timeline shows, for each version, what changed: prompt, code, lib, config or status. pull --version rewrites workspace files from an earlier version — that is the rollback, to be pushed again like any normal change.

Publish and consume#

Once activated, the agent is invoked over HTTPS:

curl -N https://agents.agent-forge.cc/my-agent/invoke \
  -H "x-api-key: fak_…" \
  -H "content-type: application/json" \
  -d '{"query":"..."}'

The response is an SSE stream ending with {"type":"final","output":…}.

forge keys#

forge keys create production
forge keys list
forge keys revoke <id>

The key is shown once only. It grants access to every agent in the team: keep it on your servers, never in browser code.

Secrets and environment#

forge secret set my-agent MY_API_KEY=…

Sets or rotates a secret on the deployed worker. This is the only correct way to inject a key for a custom tool — never hardcoded, never in a versioned configuration file.

forge env pull writes deployment variables into .env.forge (git-ignored), for local development inside the source repository.

Billing and LLM keys#

forge status
forge llm set gateway sk-…
forge credit add 20
forge credit history

forge status shows credit, the team's BYOK keys and this month's web-search quota. forge llm set gateway|openrouter sets the team key: runs then go through your provider and credit is no longer consumed. forge llm clear returns to platform keys.

forge credit add <amount> opens a secure payment page (minimum $10). Credit is applied as soon as payment is confirmed, regardless of the browser tab; forge status is authoritative.

Team#

forge invite <email> invites a colleague to the current team — administrators only. Remember to include the download page in your message: your guest has no way to sign in yet.

Local administration#

forge ui
forge ui --port 5180 --open

Launches the admin interface, embedded in the binary, on http://localhost:36743 by default: agents, runs and detailed traces, versions, verdicts, billing settings. forge app is the double-click mode (installs the CLI, then opens the interface).

Exit codes#

Every command returns 0 on success and 1 on error, with the message prefixed by ✗. forge diff is the useful special case in scripts: 1 means "different", not "failed".