CLI

The peretyn CLI compiles your schema into a model, publishes the model to an environment, and checks assertions against it.

InstallCopy Anchor Link

Download the binary for your platform from the latest @peretyn/go-cli release on GitHub:

Rename it to peretyn, make it executable, and put it on your PATH. peretyn build also needs Node.js 24 or later, because it runs your schema module.

ConfigureCopy Anchor Link

The CLI reads settings from flags, then environment variables, then peretyn.json in the current directory. The first one that is set wins.

Commit peretyn.json with your schema, and keep the API key in the environment:

{
  "control": "https://app.peretyn.dev",
  "runtime": "https://app.peretyn.dev",
  "model": "peretyn.model.json"
}

Set PERETYN_CONFIG to read the file from another path.

The API key identifies the environment, so no command takes a project or environment id.

peretyn buildCopy Anchor Link

Compiles a TypeScript schema module into a model file. It needs no API key.

peretyn build --schema schema.ts

peretyn planCopy Anchor Link

Compares the model file with the model that the environment runs, and prints what apply would change:

peretyn plan

plan: changes to apply
  ~ type document
      + editor

run: peretyn apply --label <label>

peretyn applyCopy Anchor Link

Publishes the model file to the environment under a label. --label is required.

peretyn apply --label v2

peretyn testCopy Anchor Link

Runs the checks in an assertions file against the environment, and fails when a verdict differs from the one you expect:

{
  "assertions": [
    {
      "subject": "user:alice",
      "relation": "can_view",
      "object": "document:roadmap",
      "expect": true
    },
    {
      "subject": "user:bob",
      "relation": "can_edit",
      "object": "document:roadmap",
      "expect": false
    }
  ]
}

peretyn test

✓ document:roadmap#can_view@user:alice  true
✓ document:roadmap#can_edit@user:bob  false

2 passed, 0 failed (2 total)

--file reads the assertions from another path. The default is peretyn.assertions.json.