Orchard

CLI

Mon, 01 Jan 0001 00:00:00 +0000

CLI reference#

orchard <command> [arguments] [flags]

Global flags#

Flag	Type	Default	Description
`--var key=value`	string map	—	Override a scenario variable. Repeatable: `--var a=1 --var b=2`.
`--no-color`	bool	`false`	Disable colored output.

Environment variables

Name	Effect
`NO_COLOR`	If set to any value, disables colored output. Equivalent to `--no-color`.

`orchard init`#

orchard init [directory]

Scaffold a new Orchard project with a starter scenario and component.

Argument	Description
`[directory]`	Where to create the files. Defaults to `.`. Created if it doesn’t exist.

What it creates

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

Orchard ships as a single Go binary. There is no daemon, no server, and no database of its own — it reads HCL files and talks to the systems you configure.

Install from source#

go install github.com/pthm/orchard@latest

This installs orchard into $GOBIN (defaulting to $HOME/go/bin). Make sure that directory is on your PATH.

Verify the install:

orchard --help

You should see the top-level command with run, plan, and list subcommands.

Requirements#

Go 1.22 or newer if installing from source.
A target system to drive. Orchard itself is just an orchestrator — you need something for it to talk to. For the built-in providers that means a reachable PostgreSQL database (for builtin/postgres), an HTTP endpoint (for builtin/http), or a shell environment (for builtin/exec).

Prebuilt binaries#

Prebuilt binaries are not yet published. Until then, go install is the supported path.

Provider protocol

Mon, 01 Jan 0001 00:00:00 +0000

Provider protocol#

Orchard and its providers communicate using a line-oriented JSON protocol over stdio. This page defines the wire format. If you’re writing a provider, these are the exact bytes you need to read and write.

Framing: JSON Lines#

Every message is a single JSON object on its own line, terminated by \n. Readers split on \n, parse the line as one JSON value, and match it to a request by id.

Scenarios

Mon, 01 Jan 0001 00:00:00 +0000

Scenarios#

A scenario is the top-level entrypoint in Orchard. It is the thing a user runs. A scenario declares the providers it needs, accepts parameters via variables, composes components and actions, and exposes outputs.

scenario "merchant_with_chargeback" {
 required_providers {
 postgres = { source = "builtin/postgres" }
 }

 variable "dsn" {}
 variable "merchant_name" {
 default = "Acme Corp"
 }

 provider "postgres" {
 dsn = var.dsn
 }

 component "merchant" "base" {
 source = "../components/merchant.hcl"
 inputs = { name = var.merchant_name }
 }

 output "merchant_id" {
 value = component.merchant.base.id
 }
}

What goes inside a scenario#

A scenario file contains exactly one scenario "<name>" { ... } block. Inside that block, you can declare:

Seeding a demo environment

Mon, 01 Jan 0001 00:00:00 +0000

Seeding a demo environment#

Goal. Produce a database that tells a compelling story when someone opens the product. Not just rows — a believable narrative: customers with histories, orders with realistic timing, payments with a mix of outcomes.

Why Orchard. Hand-written SQL seed scripts rot. They drift from the schema, they can’t vary the story for different audiences, and they don’t compose. A scenario describes the story once; variables let you reshape it per demo.

Components

Mon, 01 Jan 0001 00:00:00 +0000

Components#

A component is a reusable unit of state. It’s the Orchard equivalent of a function: it takes inputs, performs some work, and returns outputs. Scenarios compose components to describe complex state without repeating themselves.

Defining a component#

A component lives in its own file. The file contains one component "<name>" { ... } block:

# components/merchant.hcl
component "merchant" {
 variable "name" {
 default = "Default Merchant"
 }

 variable "region" {
 default = "us"
 }

 action "postgres_query" "create" {
 query = "INSERT INTO merchants (name, region) VALUES ('${var.name}', '${var.region}') RETURNING id, name, region"
 }

 output "id" { value = action.postgres_query.create.id }
 output "name" { value = action.postgres_query.create.name }
 output "region" { value = action.postgres_query.create.region }
}

A component has the same vocabulary as a scenario — variables, actions, outputs — but no required_providers or provider blocks. Components inherit their providers from the enclosing scenario.

Execution model

Mon, 01 Jan 0001 00:00:00 +0000

Execution model#

A provider is a process. Orchard starts it, talks to it, and stops it. This page documents that lifecycle in detail so you know exactly what your provider code has to handle.

One process per scenario#

In run mode, Orchard spawns one provider subprocess per provider declaration in the scenario. The process stays alive for the duration of the scenario, handles all actions routed to that provider, and receives shutdown at the end.

HCL schema

Mon, 01 Jan 0001 00:00:00 +0000

HCL schema reference#

Every block and attribute Orchard’s parser accepts. The two authoring contexts are scenario files and component files.

Scenario files#

A scenario file contains exactly one scenario block.

`scenario`#

scenario "<name>" {
 description = "..." # optional
 tags = ["a", "b"] # optional

 required_providers { ... }
 variable "<name>" { ... }
 provider "<name>" { ... }
 component "<type>" "<name>" { ... }
 action "<type>" "<name>" { ... }
 output "<name>" { ... }
}

A single HCL file may contain multiple scenario blocks. When it does, orchard run and orchard plan require --scenario <name> to pick one. Single-scenario files work without the flag.

Manual UAT testing

Mon, 01 Jan 0001 00:00:00 +0000

Manual UAT testing#

Goal. Reproducible test cases for QA and stakeholders. “A subscription with three failed payments” should be one command, not a fifteen-minute click-through.

Why Orchard. UAT scripts usually live as a README page of SQL snippets, a shared Notion doc, or inside someone’s head. Turning them into scenarios makes them runnable, version-controlled, and reviewable.

Pattern: test case per scenario#

Each distinct UAT case becomes a scenario file. Name them after the test case:

Setup

Mon, 01 Jan 0001 00:00:00 +0000

Setup#

Orchard is configuration-free: there is no global config file, no workspace init, and no state directory. A project is just a directory of .hcl files.

Recommended layout#

my-project/
├── scenarios/
│ ├── dev.hcl
│ ├── demo.hcl
│ └── integration.hcl
└── components/
 ├── merchant.hcl
 └── order.hcl

scenarios/ — one file per runnable scenario. Scenario files are what you pass to orchard run.
components/ — reusable building blocks. Components are referenced from scenarios with source = "../components/<name>.hcl".

This layout is a convention, not a requirement. Orchard doesn’t care where files live; source paths are resolved relative to the file that references them.

Expressions

Mon, 01 Jan 0001 00:00:00 +0000

Expression reference#

Orchard uses HCL expressions with a cty type system. This page covers the reference namespaces, type expressions, and available functions.

Reference namespaces#

Five reference namespaces are available inside expressions:

Form	Scope	Available when
`var.<name>`	Scenario (or component) variables.	Immediately — resolved up front.
`action.<type>.<name>.<output>`	Action outputs.	After the referenced action completes.
`component.<type>.<name>.<output>`	Component instance outputs.	After the component resolves.
`var.<name>` (inside a component)	The component’s own variables.	Immediately, scoped to the component.
`self.<output>`	The current action’s own outputs.	Inside `lifecycle { teardown { } }` blocks only.

Variable references#

provider "postgres" {
 dsn = var.dsn
}

action "postgres_query" "insert" {
 query = "INSERT INTO t (name) VALUES ('${var.name}')"
}

Variable references are resolved at plan time. They cannot participate in the dependency graph — if you need ordering, reference an action or component output instead.

First scenario

Mon, 01 Jan 0001 00:00:00 +0000

Your first scenario#

This page walks through writing and running a small scenario that inserts a merchant row and a product row into Postgres, wiring the merchant’s generated ID into the product insert.

Prerequisites#

You’ll need a PostgreSQL database you can write to and two tables:

CREATE TABLE merchants (
 id SERIAL PRIMARY KEY,
 name TEXT NOT NULL,
 region TEXT NOT NULL
);

CREATE TABLE products (
 id SERIAL PRIMARY KEY,
 merchant_id INT NOT NULL REFERENCES merchants(id),
 name TEXT NOT NULL,
 price NUMERIC NOT NULL
);

Write the scenario#

Create scenarios/hello.hcl:

Functions

Mon, 01 Jan 0001 00:00:00 +0000

Functions#

Orchard exposes 56 functions in every expression — variable defaults, provider configs, component inputs, action attributes, scenario outputs, component outputs, and teardown bodies. All names use lowercase compound words with no separators (jsonencode, timeadd, timeseries, …).

Functions marked with (impure) may return different values on each call. That’s intentional — scenarios are single-shot imperative runs, not convergent plans.

Collections#

`concat`#

concat(lists...) → list

Concatenate two or more lists into one.

Parameter	Type	Description
`lists...`	`list`	Variadic.

concat(["a"], ["b", "c"])

→ ["a", "b", "c"]

Local development environments

Mon, 01 Jan 0001 00:00:00 +0000

Local development environments#

Goal. New engineers clone the repo, run one command, and have a working local database with enough data to develop against. No “ask Slack for a SQL dump.”

Why Orchard. A single authoritative scenario replaces the tribal-knowledge approach. The scenario lives in the repo and evolves with the schema.

Pattern: one “dev” scenario per service#

scenarios/
└── dev.hcl

dev.hcl is the canonical “everything you need to boot up locally.” Engineers run it after applying migrations.

Providers

Mon, 01 Jan 0001 00:00:00 +0000

Providers#

A provider is the runtime that turns a declarative HCL action into a real side effect. builtin/postgres opens a connection and runs SQL. builtin/http makes HTTP requests. builtin/exec spawns child processes. Custom providers can do anything you can write a binary for.

The two kinds of providers#

Built-in providers are compiled into the orchard binary. They’re always available and need no installation. Today that’s:

builtin/postgres
builtin/http
builtin/exec

External providers are separate binaries that speak Orchard’s provider protocol over stdio. They’re referenced by path:

Schema and types

Mon, 01 Jan 0001 00:00:00 +0000

Schema and types#

A provider’s schema is its contract with Orchard. It describes what configuration the provider accepts, what action types it handles, and what each action’s attributes and outputs look like. Orchard uses the schema to type-check scenarios at plan time before a single action runs.

`ProviderSchema`#

{
 "name": "stripe",
 "version": "0.3.0",
 "protocol": "1",
 "config": {
 "api_key": { "type": "string", "required": true, "description": "..." }
 },
 "actions": {
 "charge": { ... },
 "refund": { ... }
 }
}

Field	Type	Description
`name`	`string`	Unique provider identifier. Users see this in error messages.
`version`	`string`	Provider version. Freeform string; use semver.
`protocol`	`string`	Wire protocol version. Must be `"1"` today.
`config`	`map[string]AttrSchema`	Attributes accepted in the `provider "name" { }` block.
`actions`	`map[string]ActionSchema`	Action types this provider handles, keyed by action type name.

`ActionSchema`#

{
 "description": "Execute a SQL statement and capture the first row",
 "attrs": {
 "query": { "type": "string", "required": true }
 },
 "outputs": { "type": "any" }
}

Field	Type	Description
`description`	`string`	Free-text description. Surfaced in docs and errors.
`attrs`	`map[string]AttrSchema`	Attributes the action accepts.
`outputs`	`AttrSchema` (optional)	Shape of what the action returns. Omit if the action has no outputs.

`AttrSchema`#

{
 "type": "string",
 "required": true,
 "default": "\"GET\"",
 "description": "HTTP method"
}

Field	Type	Description
`type`	`string`	Textual cty type expression. See below.
`required`	`bool`	Whether the attribute must be provided.
`default`	JSON raw	Optional default value, JSON-encoded cty. Applied when the attribute is omitted.
`description`	`string`	Free-text description.

Type expressions#

Types are written as cty type expressions in string form:

External providers

Mon, 01 Jan 0001 00:00:00 +0000

External providers#

External providers are binaries that live outside the orchard tree and speak Orchard’s provider protocol over stdio. Scenarios use them exactly like built-in providers — the only difference is the source string.

If you want to build a custom provider, see Extending Orchard. This page covers how to use an existing external provider from a scenario.

Declaring an external provider#

required_providers {
 stripe = { source = "exec:./bin/orchard-stripe" }
}

The source format is exec:<path>, where <path> is an executable file:

Integration testing

Mon, 01 Jan 0001 00:00:00 +0000

Integration testing#

Goal. Shared, versioned setup for your integration test suite. Each test needs a predictable slice of the database; Orchard produces that slice from a scenario.

Why Orchard. Integration tests tend to accumulate setup code in Go/Python/ whatever — createMerchant(t, db, "Acme") functions that duplicate what your product already does. Orchard scenarios are a source of truth that both tests and local dev can share.

Pattern: scenario per test fixture#

test/
├── integration/
│ ├── fixtures/
│ │ ├── empty.hcl
│ │ ├── one_merchant.hcl
│ │ └── merchant_with_orders.hcl
│ └── ...

Each test declares which fixture it needs and runs that scenario as part of setup.

Wiring

Mon, 01 Jan 0001 00:00:00 +0000

Wiring#

Wiring is how outputs from one step flow into the inputs of the next, and how Orchard decides the order to execute steps in. You never write a graph by hand — you write references in expressions, and Orchard derives the graph from them.

References#

Four reference namespaces are in scope inside expressions:

Form	Resolves to	Available when
`var.<name>`	A scenario or component variable.	Plan time — variables are resolved up front.
`action.<type>.<name>.<output>`	An output from another action.	After that action completes.
`component.<type>.<name>.<output>`	An output from a component instance.	After that component resolves.
`var.<name>` (inside a component)	The component’s own variable.	As soon as the component runs.

References can appear inside any attribute expression — in action bodies, provider configs (variables only), output values, or component inputs.

Writing a provider

Mon, 01 Jan 0001 00:00:00 +0000

Writing a provider in Go#

This page walks through building a small custom provider end-to-end. The provider, echo, has two actions:

echo — returns its input attributes as outputs.
randomize — takes a prefix and returns <prefix>-<random-hex>.

The source is tiny (~120 lines) but covers every part of the protocol: the schema subcommand, the RPC loop, method dispatch, and error handling.

Project layout#

orchard-echo/
├── go.mod
└── main.go

mkdir orchard-echo && cd orchard-echo
go mod init github.com/you/orchard-echo

No dependencies — this example talks JSON directly. Providers that want to use Orchard’s types can import github.com/pthm/orchard/pkg/protocol.

Composing components

Mon, 01 Jan 0001 00:00:00 +0000

Composing components#

Goal. Break a large scenario down into reusable components. Think of components like functions: small, well-named, tested in isolation, reused across scenarios.

When to extract a component#

Extract a component when you notice one of these signals:

Repetition. The same 5–10 lines of HCL appear in three scenarios. Make them a component.
Named concepts. When you find yourself wanting to say “a merchant” instead of “three SQL inserts and two HTTP calls”, you’ve found the component boundary.
Scope variation. A small concept today might need to expand. A component gives you a single place to change behavior for all callers.

Don’t extract:

Plan vs run

Mon, 01 Jan 0001 00:00:00 +0000

Plan vs run#

Orchard has two execution modes. They share parsing, validation, and graph construction but diverge on how they deal with providers and side effects.

`orchard plan`#

orchard plan is a read-only preview. It:

Parses the scenario file and any component files it references.
Loads provider schemas.
Validates the scenario: every reference resolves, every required attribute is set, every type matches.
Builds and sorts the dependency graph.
Prints the plan — what will run, in what order, with what inputs.

plan never configures a provider and never executes an action. It cannot open database connections, make HTTP requests, or spawn subprocesses. For built-in providers, plan skips Configure entirely. For external providers, plan uses a short-lived schema probe that runs <binary> schema, reads the schema JSON, and exits immediately.

Publishing

Mon, 01 Jan 0001 00:00:00 +0000

Publishing a provider#

Once your provider works, users need a way to install and use it. Today that means: give them a binary and have them reference it by path. A registry is future work.

Consumption model#

Scenarios reference providers by source string:

required_providers {
 stripe = { source = "exec:./bin/orchard-stripe" }
}

The path is resolved relative to the scenario file that declares the provider. Absolute paths work too. The binary must be executable.

Lifecycle and teardown

Mon, 01 Jan 0001 00:00:00 +0000

Lifecycle and teardown#

Orchard creates state. Good tools also clean it up. Every orchard run writes a run record describing what happened; orchard teardown uses that record to reverse it.

Run records#

After every orchard run, Orchard writes a JSON file named orchard_<scenario>_run_<id>.json into the current directory. The filename’s <id> prefix is sortable — YYYYMMDDTHHMMSSZ_<8hex> — so listing the directory in your shell gives you runs in chronological order.

$ orchard run scenarios/dev.hcl
scenario: dev
executing...
 ok action.postgres_query.create_merchant (4ms)
 ok action.postgres_query.create_product (2ms)
...

$ ls orchard_dev_run_*.json
orchard_dev_run_20260415T103045Z_a3f29e5b.json

The record captures:

exec

Mon, 01 Jan 0001 00:00:00 +0000

exec#

Source: builtin/exec

Shell command execution.

Provider configuration#

Name	Type	Required	Default	Description
`dir`	`string`	no	—	Default working directory for commands. Relative paths are resolved against the process cwd.
`env`	`map(string)`	no	—	Default environment variables merged into every action’s env.

Actions#

`exec_run`#

Run a program and capture stdout/stderr/exit_code.

Non-zero exit is an error by default — the action fails and downstream actions don’t run.

Run a program with explicit arguments.

http

Mon, 01 Jan 0001 00:00:00 +0000

http#

Source: builtin/http

HTTP request provider.

Provider configuration#

Name	Type	Required	Default	Description
`base_url`	`string`	no	—	Prepended to relative URLs in requests. When unset, URLs must be absolute.
`default_headers`	`map(string)`	no	—	Headers added to every request; per-request headers take precedence.
`timeout_seconds`	`number`	no	`30`	Per-request timeout in seconds applied to the full request/response round-trip.

Actions#

`http_request`#

Issue an HTTP request and capture the response.

Simple GET against a relative path resolved via base_url.

postgres

Mon, 01 Jan 0001 00:00:00 +0000

postgres#

Source: builtin/postgres

PostgreSQL data operations.

Provider configuration#

Name	Type	Required	Default	Description
`dsn`	`string`	yes	—	PostgreSQL connection string (e.g. `postgres://user:pass@host:5432/db`).

Actions#

`postgres_copy`#

Bulk-load rows into a table via PostgreSQL COPY FROM STDIN. Dramatically faster than row-by-row INSERT for fixture data — a 10,000-row CSV loads in a single network round-trip.

Provide data inline via data or reference a file via file. The two are mutually exclusive. file paths are resolved relative to the scenario file by the engine, so file = "./fixtures/merchants.csv" works from any cwd.

Orchard

CLI

CLI reference#

Global flags#

orchard init#

Installation

Installation#

Install from source#

Requirements#

Prebuilt binaries#

Provider protocol

Provider protocol#

Framing: JSON Lines#

Scenarios

Scenarios#

What goes inside a scenario#

Seeding a demo environment

Seeding a demo environment#

Components

Components#

Defining a component#

Execution model

Execution model#

One process per scenario#

HCL schema

HCL schema reference#

Scenario files#

scenario#

Manual UAT testing

Manual UAT testing#

Pattern: test case per scenario#

Setup

Setup#

Recommended layout#

Expressions

Expression reference#

Reference namespaces#

Variable references#

First scenario

Your first scenario#

Prerequisites#

Write the scenario#

Functions

Functions#

Collections#

concat#

Local development environments

Local development environments#

Pattern: one “dev” scenario per service#

Providers

Providers#

The two kinds of providers#

Schema and types

Schema and types#

ProviderSchema#

ActionSchema#

AttrSchema#

Type expressions#

External providers

External providers#

Declaring an external provider#

Integration testing

Integration testing#

Pattern: scenario per test fixture#

Wiring

Wiring#

References#

Writing a provider

Writing a provider in Go#

Project layout#

Composing components

Composing components#

When to extract a component#

Plan vs run

Plan vs run#

orchard plan#

Publishing

Publishing a provider#

Consumption model#

Lifecycle and teardown

`orchard init`#

`scenario`#

`concat`#

`ProviderSchema`#

`ActionSchema`#

`AttrSchema`#

`orchard plan`#

`exec_run`#

`http_request`#

`postgres_copy`#