One minute to your first proof.

Set up the project

Writes a minimal sodl.yaml, an environments/local.yaml, and a starter scenarios/first.sodl. It refuses if sodl.yaml already exists — never a silent clobber. Run sodl init -probe first if you want to see what SODL found without writing anything.

$ sodl init -yes

See what SODL understood — and what it could not

Still no running service, no credentials, no deployment. This is SODL’s unconditional half: give it your contracts and it shows you your system — entities, lifecycles, relationships, state machines — with the things you did not know surfaced as findings.

$ sodl analyze
$ sodl model -open    # your system, drawn

People routinely learn something here. A declared lifecycle state nothing can reach. An entity with no lifecycle at all. Two operations nothing in the contract lets anyone read back.

Tell the environment where your service lives

Everything a run needs to reach your service lives in the environment file, not on the command line. context: is how header-scoped things like tenancy work with no flags — every key is attached to every request. Non-secret values only.

name: local
endpoint:
  grpc: localhost:9090        # or http: https://api.local
context:
  X-Tenant-Id: your-tenant    # optional
principals:
  admin:                      # only when a scenario says `as admin`
    provider: header

Prove it, then share the evidence

sodl run takes no arguments inside a project — scenarios/ is the default. It walks the tree, runs every scenario, and writes an immutable record. sodl report -open renders the latest record as one self-contained page.

$ sodl run
$ sodl report -open

While authoring, sodl check is the faster loop — same derivation, same runner, read back as one verdict with remediation. It writes no evidence record: running is the evidence-producing act.