First run

This tutorial initializes a repo for Orchard, generates a TypeScript workflow artifact, and runs it on Orchard's in-process runtime. There is no database or external service to set up: orchard run executes the workflow as promises inside the current process via createLocalRuntime().

1. Install and initialize this directory

pnpm install
pnpm exec orchard init

orchard init writes a local, ignored .orchard/config.json with a stable per-directory queue namespace derived from the current working directory:

json

{
  "version": 1,
  "workflowDir": ".orchard/workflows",
  "queueNamespace": "orchard_myrepo_ab12cd34",
  "queues": {
    "workflow": "orchard_myrepo_ab12cd34_workflow",
    "tasks": "orchard_myrepo_ab12cd34_tasks"
  }
}

These queue names are part of the generated-artifact contract (see Generate a workflow with the CLI), but the in-process runtime tracks them only as metadata — there is no worker pool scheduling against them. Do not commit this generated config file; each worktree should create its own.

2. Check readiness

pnpm exec orchard doctor --json

doctor --json prints machine-readable readiness details: Node/pnpm, optional harness CLI tooling, and repo config. There is no database, schema, or queue to set up before running a workflow.

3. Generate and preview a workflow

pnpm exec orchard generate \
  --harness codex \
  --model gpt-5.5 \
  --prompt "Create a PR summary workflow" \
  --artifact-name pr-summary \
  --json

pnpm exec orchard preview --uuid <uuid from generate JSON> --json

Preview reads manifest metadata and validates that the saved source still matches the recorded sourceHash; it does not import or execute the artifact.

4. Run the workflow

pnpm exec orchard run .orchard/workflows/pr-summary-<uuid>.ts \
  --harness codex \
  --model gpt-5.5 \
  --input-json '{"prompt":"Summarize this repo"}' \
  --json

orchard run imports the artifact, calls registerWorkflow({ app, harness, cwd, queues }) against the in-process runtime, spawns the root workflow, and prints workflowID/taskID plus the final state and result snapshot. Pass the same harness/model you want workflow tasks to use when generated code calls harnessCall.

5. Read the result

orchard run writes status lines ([orchard:workflow] ...) to stderr as the workflow progresses, then prints the workflow's final state and result snapshot to stdout. Nothing is persisted: once the process exits, that printed output is the only record of the run — there is no follow-up command to inspect, retry, or resume it.

First run ​

1. Install and initialize this directory ​

2. Check readiness ​

3. Generate and preview a workflow ​

4. Run the workflow ​

5. Read the result ​

Related ​