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

# guild factory

> Set up, start, inspect, and test a Software Factory.

Set up and inspect a [Software Factory](/platform/factory), an automated pipeline that turns a labeled GitHub or Jira issue into a reviewed pull request. `guild factory init` wires a workspace to a repository from your terminal, `guild factory start` starts a pipeline for a specific issue, `guild factory status` reports the factory's state in a workspace, and `guild factory test` runs an optional end-to-end check.

## init

Wire a Guild workspace to a GitHub repository so that labeling an issue starts a pipeline.

```bash theme={null}
guild factory init                       # Set up a Software Factory
guild factory init owner/repo            # Target a specific repository
guild factory init owner/repo --yes      # Skip confirmation prompts
```

For a Jira-backed Factory, pass the connection, site, and project explicitly:

```bash theme={null}
guild factory init owner/repo \
  --issues jira \
  --issues-credential-id <credential-id> \
  --jira-cloud-id <cloud-id> \
  --jira-project-key <project-key>
```

| Argument | Description                                                                   |
| -------- | ----------------------------------------------------------------------------- |
| `[repo]` | The GitHub repository to wire to the factory, such as `owner/repo`. Optional. |

| Option                        | Description                                                                                                                                                      |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--workspace <id>`            | The workspace to set up as a factory.                                                                                                                            |
| `--code-credential-id <id>`   | Reuse a specific eligible GitHub credential, given as its UUID. Defaults to the saved choice, or to the sole connection with access to the requested repository. |
| `--issues <provider>`         | The issue tracker that triggers pipelines: `github` or `jira`. Defaults to `github`.                                                                             |
| `--issues-credential-id <id>` | ID of the existing Jira credential the Factory uses to read issues. Selects the exact Jira connection instead of resolving one at runtime.                       |
| `--jira-cloud-id <id>`        | Cloud ID of the Jira site, used when creating a new Jira connection.                                                                                             |
| `--jira-project-key <key>`    | Key of the Jira project the Factory reads issues from, such as `ENG`.                                                                                            |
| `--label <name>`              | The issue label that starts a pipeline.                                                                                                                          |
| `--reuse-workspace`           | Reuse an existing workspace instead of creating a new one.                                                                                                       |
| `--skip-environment`          | Skip runtime environment setup during initialization.                                                                                                            |
| `--yes`                       | Accept the proposed actions without confirming.                                                                                                                  |

<Note>
  Jira setup requires an explicit connection and project. The CLI persists the credential, site, and project you select, so later runs do not guess which Jira credential to use. To trigger a Jira Factory after setup, add both a routing label and an action label to an issue. See [Live](/platform/factory-setup-wizard#live).
</Note>

### Reusing a GitHub connection

The CLI reuses an existing GitHub connection only after it verifies access to the requested repository. The connection must belong to the factory's account, use the current Guild GitHub App configuration, and be account-wide or scoped to the saved workspace. A saved choice takes precedence; a missing or incompatible saved connection requires an explicit replacement.

When several connections can access the repository, interactive setup asks which one to use. Pass `--code-credential-id <id>` to select one without a prompt.

<Note>
  An explicit `--code-credential-id` that lacks access to the repository returns `github_repo_unavailable` rather than silently falling back to another connection. On an already-live factory, `guild factory init` refuses `--code-credential-id`, even when it names the current connection. Omit the flag to get the existing factory receipt.
</Note>

### Driving factory setup from an agent

Run `guild factory init` in agent mode to set up a factory without interactive prompts:

```bash theme={null}
guild factory init acme/widgets --mode jsonl --non-interactive --yes
```

`--mode jsonl` prints one envelope per line as each step transitions, `--non-interactive` shows no prompts, and `--yes` answers every question that has a safe default. Without `--yes`, the run refuses immediately with `confirmation_required`.

When multiple GitHub connections can access the repository, `--yes` does not choose between them. The run returns the `github_credential_required` state with the exact `--code-credential-id` options instead. Prompt the user to pick one, then rerun the command with their selection:

```bash theme={null}
guild factory init acme/widgets --code-credential-id <uuid> --mode jsonl --non-interactive --yes
```

## start

Start the configured Factory pipeline for a GitHub issue or a Jira issue in the Factory's configured project.

```bash theme={null}
guild factory start <issue-url> --workspace <id>              # Start the pipeline for an issue
guild factory start <issue-url> --workspace <id> --dry-run    # Validate without starting
guild factory start <issue-url> --workspace <id> --mode json  # Emit a machine-readable receipt
```

`guild factory start` validates the issue URL and the workspace before it starts the pipeline. Starting is idempotent: running the command again for the same issue returns the current execution instead of starting a second pipeline, so a rerun recovers the in-progress work rather than duplicating it.

| Argument      | Description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| `<issue-url>` | The full GitHub issue URL, or the Jira browse URL for an issue in the configured project. |

| Option             | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `--workspace <id>` | The Factory workspace, given as an ID or name. Required.            |
| `--dry-run`        | Validate the issue URL and workspace without starting the pipeline. |

## status

Show the status of the Software Factory in a workspace.

```bash theme={null}
guild factory status                            # Show factory status for the default workspace
guild factory status --workspace <id>           # Specify a workspace
guild factory status --workspace <id> --watch   # Refresh the status every 5 seconds
```

| Option             | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| `--workspace <id>` | The workspace to inspect.                                                |
| `--watch`          | Poll for status changes every 5 seconds until you interrupt with Ctrl-C. |

Add `--watch` to follow the factory's status live. In a terminal, the command refreshes the view in place every 5 seconds. When you pipe the output, it appends a timestamped snapshot on each change instead of redrawing. With `--mode jsonl`, each semantic change emits one snapshot containing the complete factory list; changes to observation timestamps alone do not emit a snapshot. Press Ctrl-C to stop watching.

<Warning>
  `--watch` cannot be combined with `--mode json`, because a live stream cannot be a single JSON document. Use `--mode jsonl` for machine-readable snapshots. See [Global options](/cli/commands#global-options).
</Warning>

`guild factory status` reports each unit of durable Factory-started work with its execution ID and lifecycle state. Lifecycle states are `dispatching`, `queued`, `running`, `failed`, and `runtime_complete`. When a workspace has no Factory-started work, the `work` field is empty.

## test

Run an optional end-to-end test of a Software Factory. The test previews a generated issue, runs it with agent credits to produce a documentation-only pull request, and then closes the issue and pull request it created. Each command works against a run ID returned by the preview step.

```bash theme={null}
guild factory test preview --workspace <name>                        # Preview the test; returns a run ID and approval digest
guild factory test run <run-id> --approve <digest> --accept-credits  # Run the approved test using agent credits
guild factory test status <run-id> --watch                           # Watch the test run status
guild factory test cleanup <run-id>                                  # Preview cleanup of the generated issue and PR
guild factory test cleanup <run-id> --approve <digest>               # Apply the cleanup
```

| Option                | Description                                                                                                                            |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--workspace <name>`  | The Factory workspace to test, given as an ID or name. Required by `preview`.                                                          |
| `--approve <digest>`  | The approval digest to apply. `run` takes the digest from `preview`; `cleanup` takes the separate digest from its own cleanup preview. |
| `--accept-credits`    | Required by `run`. Confirms the run consumes real agent credits.                                                                       |
| `--watch`             | For `status`, keep observing until the test passes, fails, or is blocked.                                                              |
| `--timeout <seconds>` | For `status --watch`, the maximum time to watch, from 1 to 3600 seconds. Defaults to 900. Stopping the watch does not cancel the test. |

<Warning>
  `guild factory test run` requires `--accept-credits` and spends real agent credits with no hard spend cap. Run `guild factory test cleanup` afterward to close the generated test issue and pull request.
</Warning>

<Note>
  `guild factory init`, `guild factory start`, `guild factory status`, and the `guild factory test` subcommands support `--mode json` and `--mode jsonl` for machine-readable output. In these modes each command prints a structured envelope for programmatic and agent use, and returns a non-zero exit code when the operation fails. See [Global options](/cli/commands#global-options).
</Note>