Getting Started

Follow these steps in order. Start from the current example; do not design a new workflow first.

1. Connect and authenticateCopy Anchor Link

Ask the user to sign in, select the intended organization, and connect the repository.

npm install -g @usestitch/cli
stitch auth login
stitch auth whoami
stitch repositories list
git rev-parse --show-toplevel
git remote -v

Node.js 24+ is required. Alternatively use bunx @usestitch/cli or npx @usestitch/cli. For another deployment, set FACTORY_URL to its HTTPS origin. Give the user the login result's verificationUrl and userCode; wait for authenticated. whoami must return the intended non-null organizationId. Match the checkout's GitHub owner/repo to an entry with active: true. Save its id and defaultBranch. Stop if access or the checkout cannot be verified.

2. Download the current exampleCopy Anchor Link

At the verified repository root, read repository instructions and download the current starter to stitch-factory.yaml. Preserve it byte-for-byte during this step. Stop if the download fails. Ask before replacing an existing file. Do not reconstruct the example from memory.

3. Explain and agree on changesCopy Anchor Link

Read the downloaded file. It triages issues, implements bug/enhancement/chore labels, reviews newly opened non-draft pull requests for over-engineering, and fixes feedback from work_needed labels or human change-request reviews. It does not review every push. Explain its run limits, OpenCode harnesses, BYOK Vercel sandboxes, and disabled triggers.

Inspect available repository skills and read relevant instructions. Suggest only skills you found and explain where they help. Ask whether to keep or change the workflow. Make only agreed changes; do not redesign it first.

Check the required build/review agents, code-review skill, and GitHub labels. The starter does not create them. Ask how to resolve missing dependencies. Replace the Vercel team/project placeholders. Keep triggers disabled until prerequisites are ready and activation is approved.

4. Add secrets privatelyCopy Anchor Link

stitch secrets list
stitch secrets add OPENCODE_API_KEY
stitch secrets add VERCEL_TOKEN
stitch secrets list

For the unchanged starter, these are the OpenCode API key and Vercel access token. If authentication changed, use the names now referenced in the file. Ask the user to enter values in the CLI's hidden prompt in their private terminal. Reuse existing secrets; ask before replacing them. Confirm all names exist in the active organization.

5. ValidateCopy Anchor Link

stitch validate --dry-run
stitch validate --repository <connected-repository-id>

Resolve missing dependencies and placeholders first. Fix reported errors with agreement. Validation does not apply configuration or test provider credentials.

6. Approve and pushCopy Anchor Link

Show the final changes. Ask for permission to commit and push, and separately to activate. If approved, enable only the intended triggers and validate again. Commit only agreed files. Stitch reads the default branch: another branch must be merged before configuration applies. Verify the applied state in the application, or report verification as pending. There is no CLI apply or startup command.

SchemaCopy Anchor Link

Factory JSON Schema. See CLI validation.