Skip to Content
ReferenceRule CLI

Rule CLI

trustacks rule is the command-line tool for TruStacks policy. It writes, tests, lints and signs rules in a local checkout, with no control plane and no account. It is how a rule drafted by /rule new in the app becomes a real, tested rule.

The runner image also contains review, plan, gaps and application commands. Those are internal development tools for local TruStacks stacks: they send no sign-in credentials and do not work against hosted TruStacks. They are not a supported customer interface and are not documented here. On hosted, use the web app.

Running it

There is no standalone CLI package. Run it from the runner image, which also carries opa, oras, and cosign:

docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD:/work" -w /work \
  ghcr.io/trustacks/runner:<version> \
  trustacks --help

If you work from a source checkout of the runner, uv run trustacks does the same.

Conventions

  • Exit code 0 on success, 1 on any failure.
  • Output is for people (Rich formatting). There is no JSON output mode.
  • There is no config file and no login command: trustacks rule works on local files only.

Overlay rules: trustacks rule

Every rule command takes --overlay PATH, a local checkout of your overlay repo. It defaults to the current directory and must contain environment-profile.yaml at its root. Rules live in rules/<rule_id>/.

trustacks rule new

trustacks rule new <rule_id> [--description TEXT] [--package NAME]

Scaffolds rules/<rule_id>/<rule_id>.rego and <rule_id>_test.rego. The rule ID must meet the naming standard. The package defaults to overlay.<namespace>_<name>.

The stub’s deny condition is false, so it never fires until you replace it. The test file ships one passing baseline test and a commented template for the real one. Refuses to overwrite an existing rule directory.

trustacks rule new acme.requires_runbook_link \
  --description "Every service ships a runbook link"

trustacks rule test

trustacks rule test [rule_id] [-v | --verbose]

Runs opa test on one rule’s directory, or on all of rules/. --verbose prints each test name. Exits with opa’s status. An overlay with no rules/ directory exits 0.

trustacks rule lint

trustacks rule lint [rule_id]

Checks rule ID validity, that both files exist, that the rule declares a package and a rule_metadata map keyed by its ID, then runs opa check. See Policy linter for the full list and what it does not check.

trustacks rule sign

trustacks rule sign [--bundle-ref REF] [--registry HOST:PORT] [--tag TAG]
                    [--key PATH] [--signing-config PATH]
                    [--insecure | --no-insecure]

Builds an OPA bundle from rules/ (with a rule_inventory.json), pushes it with oras, and signs the pushed digest with cosign. Every rule ID is checked against the naming standard first. It does not run lint or test.

FlagDefault
--bundle-ref<registry>/trustacks/policy/overlay/<profile name>:<tag>, where the profile name is name: in environment-profile.yaml
--registryzot.localtest.me:8080
--tagdev
--key.policy-keys/cosign.key
--signing-config.policy-keys/signing-config.json (offline, no transparency log)
--insecure / --no-insecure--insecure (plain HTTP)

The defaults target the local development registry and a local key. Hosted runners do not load overlay bundles yet, and per-customer signing keys are not built. See the constitution page.

Not in the CLI

These appeared in earlier versions of this page and do not exist: rule list, rule show, env declare, env validate, env diff, login, status, version, --output json, and ~/.trustacks/config.yaml. Browse rules on the Rules page instead.

Where to go next

Last updated on
LLM provider (BYO key)Policy linter