> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Operate the Factory

> Start work, watch progress, approve gates with labels and answer questions.

> [!NOTE]
>
> **Early Access.** Commands and behavior can change between releases.

## Local work

In an Architech session, `/sync` reads the board, `/dispatch <issue-number>` runs planned work and
`/status` shows its progress. The shell commands below control **Cloud runs**, not a local
background process.

## Start and watch Cloud work

An enabled Factory can pick up board work. You can also start a run yourself:

```bash theme={null}
architech factory runs start "Add input validation to the contact form" --repo acme/web --factory <factory-id> --json
architech factory runs list --factory <factory-id> --json
architech factory runs show <run-id> --json
architech factory runs logs <run-id> --follow --json
```

Use a repository listed in your file. `runs show` lists stage progress and open questions.
`runs logs` shows stage states, pull request URLs and the pending gate. With `--follow`, it streams
events to stderr until the run ends; the JSON result stays on stdout.

## Approve or reject a gate

> [!WARNING]
>
> Read the plan or pull request before you approve. Approval is your decision; an agent never
> grants it to itself.

Answer a gate with a label in GitHub, in the issue or pull request sidebar or on the board:

| Gate | Approve | Ask for changes (comment first) |
| - | - | - |
| Plan, on the issue | `factory:approved` | `factory:changes` |
| Merge, on the pull request | `merge-ready` | `merge:changes` |

The Factory reads the label and records who added it. It removes the plan and changes labels
once used; `merge-ready` stays until the merge. Only a person with
write access counts. Moving the card doesn't approve, and `/approve` followed by text is refused.
See [approvals by label](https://docs.mutagent.io/factory/configuration.md#approvals-by-label) for the rules and for your own
label names.

From the shell, approve only the gate the run is waiting on, `plan` or `pr`:

```bash theme={null}
architech factory runs approve <run-id> --gate plan --json
architech factory runs approve <run-id> --gate pr --json
```

To send work back from the shell, add `--reject` and say why:

```bash theme={null}
architech factory runs approve <run-id> --gate plan --reject --note "Include the rollback behavior" --json
```

## Answer a question

A stage can pause to ask you a question:

```bash theme={null}
architech factory escalations list --json
architech factory escalations answer <escalation-id> "Keep the existing public API" --json
```

Your answer resumes the stage. Read the question first: retrying the run won't supply the missing
decision.

## Pause pickup or cancel a run

```bash theme={null}
architech factory disable <factory-id> --json
```

> [!NOTE]
>
> Disabling stops new trigger-based work. Runs already in progress continue.

Cancel a run only when you want to stop its sandboxes and end it:

```bash theme={null}
architech factory runs cancel <run-id> --force --json
```

Destructive commands ask for confirmation. Without an interactive terminal you must pass
`--force`, and a coding agent must ask you first.

## Keep configuration in step

```bash theme={null}
architech factory show <factory-id> --json
architech factory pull --dry-run --json
architech factory pull --json
```

Pull writes the current Cloud version into your local file and commits it in a Git checkout.
Check the dry run first. If the file has local changes since the last sync, pull refuses instead
of discarding them; reconcile them first.

If the file has synced before, push refuses if Cloud changed since that sync. Pull,
reconcile, then push again. A file that never synced doesn't get this check:
inspect the Cloud version before you overwrite it.

> [!NOTE]
>
> Some commands make changes your local file can't hold. When this checkout has the matching
> file, they warn `factory.yaml is now behind`. `board unbind` leaves the board in the file; push
> reports the binding state but doesn't bind it again, so run `architech factory board bind <factory>`
> to reconnect. `triggers create` makes a server-only trigger; don't copy it into `triggers`, or
> you'll get a second trigger. Enable, disable and workspace settings aren't `factory.yaml` fields,
> so they don't make the file fall behind.

## Watch cost

```bash theme={null}
architech factory cost --run <run-id> --json
architech factory cost --day 2026-10-01 --json
```

Cost reports show sandbox time, tokens and dollars per role, against your caps. For every option,
see the [CLI reference](https://docs.mutagent.io/factory/reference/cli.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.