# 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.

Source: https://simforge.ai/docs/agents

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](/llms.txt) |
| Every page and the command reference in one file | [/llms-full.txt](/llms-full.txt) |
| Any page as Markdown | add `.md`: [/docs/install.md](/docs/install.md) |
| The command surface as JSON (`simforge.cli-surface/v1`) | [/docs/cli.json](/docs/cli.json), or `simforge --help --json` |
| The hosted API (`--cloud`) as OpenAPI | [/docs/openapi.json](/docs/openapi.json) |
| Agent skills for Claude Code, Codex and AGENTS.md agents | [Skills pack](/docs/skills), or `simforge skills install` |
| How an agent signs in to the hosted API without the CLI (auth.md) | [/auth.md](/auth.md) |

## Driving the CLI

1. Read the surface first: `simforge --help --json`. 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](/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

```sh
simforge mcp
```

`simforge 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](/docs/skills) gives an agent task-level instructions: the quickstart, authoring, rendering, the cloud, RL, maps, scenario packages and troubleshooting. It ships inside the CLI:

```sh
simforge skills install --claude
```