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

1. Read the surface first: simforge --help lists the commands, simforge <command> --help gives one command’s flags. Never guess a flag.
2. Parse stdout as one JSON document. On failure, key on code in the stderr JSON and follow its hint.
3. 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.
4. Sign-in needs a person: simforge login --device prints a URL and code. Relay them to the user and wait. Never print or store tokens.
5. Cloud runs cost money. Always price with --dry-run first and pass a --max-cost no higher than the budget you were given.
6. 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 mcp

simforge mcp serves the CLI over the Model Context Protocol (stdio). By default it lists a small core set of tools (under 40 KB of schemas): the authoring, render and run commands, plus a simforge tool that runs any other command from its argv. --profile full lists every command as its own tool; --only render --only scenario lists the commands under those paths; --cwd sets the working folder. Inputs are typed with each flag’s allowed values, range and default; annotations mark read-only, destructive and idempotent tools. Every call runs the same binary and returns the command’s JSON result, exit code and error once, as structured content, with a one-line text summary. 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, SimForge Gym training, maps, scenario packages and troubleshooting. It ships inside the CLI:

simforge skills install --claude