policy

omnigraph policy operates on the Cedar policy file referenced by policy.file in omnigraph.yaml. Use it to confirm the policy parses, to exercise declarative test cases, and to walk a single decision end-to-end when debugging an authorization outcome.

See Operations → Policy for the broader Cedar integration model. Actions, scopes, server runtime states, and the "tokens but no policy" trap.

policy validate

Parse the policy and report any errors. Exits non-zero on parse failure.

Usage

omnigraph policy validate [--config <path>]

Options

Example

omnigraph policy validate --config ./omnigraph.yaml

policy test

Run the declarative test cases under policy.tests (typically policy.tests.yaml). Each case describes an actor, an action, a scope, and an expected decision; the command exits non-zero if any expectation fails.

Usage

omnigraph policy test [--config <path>]

Example

omnigraph policy test --config ./omnigraph.yaml

Use this as a CI check to keep your authorization rules and your intent in sync.

policy explain

Walk a single decision and report which rule matched (or why none did).

Usage

omnigraph policy explain \
    --actor <actor-id> \
    --action <read|change|export|schema_apply|branch_create|branch_delete|branch_merge|admin> \
    [--branch <name>] \
    [--target-branch <name>] \
    [--config <path>]

Options

Example

omnigraph policy explain \
    --config ./omnigraph.yaml \
    --actor act-alice \
    --action change \
    --branch feature-x

The output prints the decision (Allow / Deny) and the matching rule, so you can trace exactly why an actor was admitted or refused.

Setting the actor for CLI writes

Cedar policy decisions need an actor identity. For CLI direct-engine writes (against local ./*.omni or s3:// URIs), supply the actor with the top-level --as flag or set cli.actor in omnigraph.yaml. With policy configured and no actor supplied, the engine-layer footgun guard denies the write rather than silently allowing it.

omnigraph --as act-alice change --uri ./graph.omni \
    --query mutations.gq \
    --name complete_task \
    --params '{"slug": "auth"}'

Remote HTTP writes ignore both knobs. The server resolves the actor from the bearer token at the auth middleware boundary.