Getting started on Orchard

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.

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.

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: