guild factory

Set up and inspect a Software 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.

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:

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.

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.

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.

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.

Driving factory setup from an agent

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

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:

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.

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.

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.

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

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.

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.

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.

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.

​init

​Reusing a GitHub connection

​Driving factory setup from an agent

​start

​status

​test

init

Reusing a GitHub connection

Driving factory setup from an agent

start

status

test