// For agents
For AI agents
Where an AI agent finds the SimForge docs, the machine-readable command surface and API, and the skills pack, and how to drive the CLI safely.
SimForge is built to be driven by agents. The CLI an agent uses is the one people use: every command prints JSON and fails with a stable error code.
Where things are#
| What | Where |
|---|---|
| Docs index for agents | /llms.txt |
| Every page and the command reference in one file | /llms-full.txt |
| Any page as Markdown | add .md: /docs/install.md |
The command surface as JSON (simforge.cli-surface/v1) | /docs/cli.json, or simforge --help --json |
The hosted API (--cloud) as OpenAPI | /docs/openapi.json |
| Agent skills for Claude Code, Codex and AGENTS.md agents | Skills pack, or simforge skills install |
| How an agent signs in to the hosted API without the CLI (auth.md) | /auth.md |
Driving the CLI#
- Read the surface first:
simforge --help --json. Never guess a flag. - Parse stdout as one JSON document. On failure, key on
codein the stderr JSON and follow itshint. - Exit 1 means fix the invocation or install what is missing. Exit 2 means the input itself is wrong: report or repair it, do not retry it unchanged.
- Sign-in needs a person:
simforge login --deviceprints a URL and code. Relay them to the user and wait. Never print or store tokens. - Cloud runs cost money. Always price with
--dry-runfirst and pass a--max-costno higher than the budget you were given. - Long-running servers (
simforge env serve,simforge world serve,simforge mcp) run until stopped: start them in their own terminal, not inside a call that waits for them to finish.
Signing in without the CLI#
An agent that calls the hosted API (/api/v1) directly signs in through auth.md, the recipe for agent sign-in that every /api/v1 401 points to (WWW-Authenticate: Bearer resource_metadata=…). The agent registers with the email of the person's SimForge account and shows the person a link and a code. The person signs in on simforge.ai, enters the code, chooses the organization and approves. The agent then gets a one-hour access token and an identity assertion that renews it.
Only that account can approve, and only once its email is verified. The person sees the agent under Account → CLI sessions and can revoke it there. A backend with no person at hand uses an API key instead.
MCP#
simforge mcpsimforge mcp serves the CLI over the Model Context Protocol (stdio): one tool per command, with its arguments and flags as typed inputs. Every call runs the same binary and returns the command's JSON result, exit code and error. --only render --only scenario limits the tools; --cwd sets the working folder. Local runs are the default; a tool call with cloud: true and a max-cost runs hosted.
Skills#
The skills pack gives an agent task-level instructions: the quickstart, authoring, rendering, the cloud, RL, maps, scenario packages and troubleshooting. It ships inside the CLI:
simforge skills install --claude