Skip to main content

Quick start

This walkthrough uses the repository's example intent, discovered components, and packaged composition sources to compile a plan and execute it.

1. Build the CLI​

make build

The commands below assume you are running them from the repository root and using the freshly built ./orun binary.

2. Inspect the shipped compositions​

./orun compositions --intent examples/intent.yaml

The example package exports Terraform, Helm, Cloudflare, Turbo, and workspace compositions from examples/compositions.

3. Lock the resolved composition sources​

./orun compositions lock --intent examples/intent.yaml

This writes examples/.orun/compositions.lock.yaml so future plans can reuse the same resolved source digests.

4. Validate the example intent and discovery tree​

./orun validate --intent examples/intent.yaml

This loads examples/intent.yaml, scans the discovery roots declared there, and validates each component against its matching composition schema.

5. Inspect the merged component model​

./orun component network-foundation --intent examples/intent.yaml --long

Use this view when you want to verify labels, overrides, subscriptions, inputs, and dependency edges before you render the final plan.

6. Compile a deterministic plan​

./orun plan --intent examples/intent.yaml --view dag

The plan is saved to .orun/plans/ and linked as latest. It is the execution boundary: a fully expanded DAG with explicit jobs, steps, and dependencies.

7. Preview execution​

./orun plan --intent examples/intent.yaml --component network-foundation --env development --output /tmp/orun-example-terraform-plan.json
./orun run --plan /tmp/orun-example-terraform-plan.json --workdir examples --gha --dry-run

--dry-run prints the execution order, working directories, runner choice, and resolved steps without mutating state.

8. Execute the plan​

./orun run --plan /tmp/orun-example-terraform-plan.json --workdir examples --gha

That command runs a dependency-free GitHub Actions-compatible job from the embedded example repo. Swap --gha for --runner docker when you want containerized execution against a plan that does not contain use: steps.

9. Inspect the result​

./orun status
./orun get jobs
./orun logs

status shows a compact execution summary. get jobs shows the grouped job tree with status icons. logs streams the raw step output.

10. Run from a component subdirectory​

cd examples/infra/infra-1/
../../../orun run --plan /tmp/orun-example-terraform-plan.json --workdir ../.. --gha

orun walks up the directory tree, finds intent.yaml, and detects that you are in the network-foundation component (via component.yaml). run automatically filters to network-foundation — equivalent to passing --component=network-foundation. Plans are always global; only execution is scoped. Use --all to run all jobs.

What happened​

  1. compositions lock resolved the declared composition sources and wrote a reproducible lock file beside the intent.
  2. validate loaded the intent, discovered component manifests, and enforced schema constraints.
  3. component showed the merged component view that feeds the compiler.
  4. plan expanded environment and component subscriptions into concrete jobs and dependency edges, then stored the result in .orun/plans/.
  5. run --dry-run previewed the immutable plan artifact.
  6. run executed it; progress was recorded in .orun/executions/.

Next steps​

  1. Read context-aware discovery to learn how orun auto-discovers the intent file and scopes to your current component.
  2. Read execution model to understand dry-run, concurrency, retries, phases, and execution records.
  3. Explore GitHub Actions and Docker runtime examples.
  4. Use orun get, orun status, and orun logs to inspect and debug ongoing or past runs.