> ## 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. # Factory CLI reference > Commands for configuration, connections, runs, approvals and triggers. > [!NOTE] > > **Early Access.** Commands and behavior can change between releases. Factory commands live under `architech factory`, not `mutagent factory`. Run them in your shell. Inside Architech, `/factory` shows Factory state; it is not the shell CLI. ```bash theme={null} architech factory --help architech factory catalog --json architech factory push --help --json ``` The catalog and per-command help describe the version installed on your machine. This page lists the commands you use. Stage sessions also have `session finish`, `session lane` and `session ask`; these use the stage's own credentials, not your sign-in. ## Output and shared options With `--json`, each call prints one `{ok, data, next}` object to stdout. On failure, read `error.code`, `error.reason` and `error.fix`. `next` suggests next commands, with reasons; review them before you act. Consent URLs and streamed events go to stderr. | Option | Meaning | | - | - | | `--json` | Machine-readable output; no interactive prompts. | | `--workspace ` | Select the workspace for this call. | | `--api-key-stdin` | Read an API key from stdin, so it never appears on the command line. | | `--non-interactive` | Never prompt. | | `--force` | Confirm a destructive command without a prompt. An agent must ask you first. | | `--help` | Show command help; combine with `--json` for its catalog entry. | ## Configuration | Command | Purpose | | - | - | | `init [file] --board github --repo acme/web` | Write a commented `factory.yaml` offline, in the same format onboarding writes. `--board` accepts `github` or `linear`; the default path is `factory.yaml`. | | `validate ` | Validate a file offline. | | `push [factory-or-path] [--dry-run]` | Send a version to Cloud; the file switches to cloud mode. In a normal Git checkout, push commits the changed file; check `committed` and the notices. | | `pull [factory-or-path] [--dry-run]` | Write the Cloud version into the local file; in a Git checkout, commit the change. | | `schema [--remote]` | Print the configuration schema, locally or from Cloud. | | `catalog` | List every command and its inputs. | `--dry-run` on push or pull writes and commits nothing; push still asks Cloud what would change. Pushing adds your installed release's framework pin only if the file has none; an existing pin stays. A successful push can still leave the file uncommitted, for example on a detached HEAD or when the commit fails. See [`factory.yaml`](https://docs.mutagent.io/factory/reference/factory-yaml) for how the versions differ. ## Setup and connections | Command | Purpose | | - | - | | `login [--timeout ]` | Browser sign-in; default wait is 300 seconds. | | `status` | Show integrations, factories and setup progress. | | `list` / `show ` | List factories or inspect a configuration's version, sync state and board. | | `enable ` / `disable ` | Start or stop trigger-based work; disable leaves in-flight runs running. | | `integrations connect --wait` | Connect a provider and wait for consent. | | `integrations reconnect --wait` | Refresh expired or narrowed permissions. | | `integrations disconnect --force` | Disconnect the provider, unbinding its boards and stopping its triggers. | | `board bind ` | Bind the board from the pushed configuration. | | `board unbind --binding --force` | Stop reading and writing that board binding. | The Factory ID is `metadata.name`. Use the IDs commands return, including the binding ID from a board response. > [!NOTE] > > Push reports `linked`, `board` and `drift`; `status` shows the same setup state. Push doesn't > link repositories or bind the board. Connect GitHub on Cloud, push the file, then run > `architech factory board bind ` once if the board is not bound. ## Runs, gates and questions | Command | Purpose | | - | - | | `runs start "" --repo acme/web --factory ` | Start without a board item. | | `runs list [--factory ] [--state ] [--limit ]` | List runs. | | `runs show ` | Inspect stages, questions and trace link. Without `--json`, it also lists each stage's command. | | `runs logs [--follow]` | Show progress; follow until the run ends. | | `runs approve --gate ` | Approve a waiting gate. The approval labels do the same from GitHub. | | `runs approve --gate plan --reject --note ""` | Reject and send work back. | | `runs cancel --force` | Stop its sandboxes and cancel the run. | | `escalations list` | List open questions. | | `escalations answer ""` | Answer and resume the paused stage. | | `cost [--run ] [--day YYYY-MM-DD]` | Inspect cost against caps. | `runs approve --sub-item ` restricts PR approval to one sub-item. Without it, PR approval covers all sub-items waiting at that gate; review their PRs before approving. A plan approval can't carry corrections: a `--note` with changes is refused. Use `--reject` with your note, or the [changes label](https://docs.mutagent.io/factory/configuration.md#approvals-by-label). ## Triggers Triggers start work; they never approve a gate. Event kinds: `board.status`, `board.label`, `board.comment`, `board.assigned`, `github.pr.approved`, `github.pr.merged`, `github.ci-failed`, `run.request`, `slack.mention`, `webhook` and `trace.threshold`. With no triggers of your own, a Factory starts `plan` when an item gets a pickup label or is assigned to `factory`, and `build` when CI fails on a `factory/*` branch. Whichever trigger fires, a run from the board also needs every pickup label and no hold label. ```bash theme={null} architech factory triggers list --factory --json architech factory triggers create --factory --kind board.label --stage plan --filter label=factory:urgent --json architech factory triggers test --event-file event.json --json architech factory triggers fire --json architech factory triggers delete --force --json ``` The create example changes your Cloud configuration. List existing triggers first so you don't duplicate board pickup. You can repeat `--filter key=value`. `--priority ` decides which matching trigger runs first (higher first). An event file holds JSON such as: ```json theme={null} {"kind":"board.label","data":{"label":"factory:urgent"}} ``` Triggers can start `plan`, or `build` for `github.ci-failed`. They can't skip an approval. `triggers fire` runs a schedule trigger (a routine) now, by its name in `factory.yaml`; add `--factory ` for another Factory and `--key ` to make a retry run it only once. See [routines](https://docs.mutagent.io/factory/triggers.md#routines). The delete command above removes triggers created through the API, such as with `triggers create`. To change a trigger, edit `triggers` in the file and push; see [`factory.yaml` triggers](https://docs.mutagent.io/factory/reference/factory-yaml#triggers) and the [Triggers and routines](https://docs.mutagent.io/factory/triggers.md). > [!NOTE] > > `triggers create` and `board unbind` warn `factory.yaml is now behind` when this checkout has > the matching file but the file can't hold the change. A push after unbind reports the binding > state; run `board bind` to reconnect. A trigger created through the API lives only on Cloud. ## Workspace display setting ```bash theme={null} architech factory settings show --json architech factory settings set --ui-mode on --json ``` Workspace admins can turn the workspace's Software Factory UI mode `on` or `off`. This doesn't enable or disable a Factory's triggers, and it isn't a `factory.yaml` field. ## Exit codes | Code | Meaning | | - | - | | `0` | Success. | | `1` | Failure, including invalid usage. | | `2` | API key refused. | | `3` | Not signed in, no workspace, or no task token for a session command. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.