See Install from binary or Run from container for instructions on how to install the cerbos binary.

This binary provides the following sub commands:


Start the PDP server


Validate, compile and run tests on a policy repo


Start a PDP and run a command within its context

Example: Running compile using the binary
./cerbos compile --help
Example: Running compile using the container
docker run -i -t ghcr.io/cerbos/cerbos:0.13.0 compile --help

server Command

Starts the Cerbos PDP.

Usage: cerbos server --config=./config.yaml

Start Cerbos server (PDP)


# Start the server

cerbos server --config=/path/to/config.yaml

# Start the server with the Admin API enabled and the 'sqlite' storage driver

cerbos server --config=/path/to/config.yaml --set=server.adminAPI.enabled=true --set=storage.driver=sqlite3 --set=storage.sqlite3.dsn=':memory:'

  -h, --help                                    Show context-sensitive help.

      --debug-listen-addr=:6666                 Address to start the gops listener
      --log-level="info"                        Log level (debug,info,warn,error)
      --config=./config.yaml                    Path to config file
      --set=server.adminAPI.enabled=true,...    Config overrides

compile Command

Runs the Cerbos compiler to validate policy definitions and run any test suites. See Policy compilation for more information.

Usage: cerbos compile <dir>

Compile and test policies


# Compile and run tests found in /path/to/policy/repo

cerbos compile /path/to/policy/repo

# Compile and run tests that contain "Delete" in their name

cerbos compile --run=Delete /path/to/policy/repo

# Compile but skip tests

cerbos compile --skip-tests /path/to/policy/repo

  <dir>    Policy directory

  -h, --help               Show context-sensitive help.

  -f, --format="pretty"    Output format (pretty,plain,json)
      --tests=STRING       Path to the directory containing tests. Defaults to policy directory.
      --run=STRING         Run only tests that match this regex
      --skip-tests         Skip tests
      --ignore-schemas     Ignore schemas during compilation
      --verbose            Verbose output on test failure

run Command

This provides a quick way to try out Cerbos. It launches a Cerbos PDP instance and then invokes a command of your choice that can then use the PDP to make access decisions. A good use case for this command is as an integration test runner. If you have written some tests that make use of Cerbos, you can run them within the context of an actual PDP instance as follows:

cerbos run -- python -m unittest

By default, the policies are loaded from the policies directory in the current working directory and HTTP and gRPC endpoints will be exposed on and respectively. Your application can obtain the actual endpoint addresses by inspecting the CERBOS_HTTP or CERBOS_GRPC environment variables.

If a file named cerbos.yaml exists in the current working directory, that file will be used as the Cerbos configuration file. You can use a different config file or override specific config values using the same flags as the server command above.

Usage: cerbos run <command> ...

Run a command in the context of a Cerbos PDP

Launches a command within the context of a Cerbos PDP. The policies are loaded by default from a directory named "policies" in the current working directory. The launched application can access Cerbos endpoints using the
values from CERBOS_HTTP or CERBOS_GRPC environment variables.

If a file named "cerbos.yaml" exists in the current working directory, it will be used as the configuration file for the PDP. You can override the config file and/or other configuration options using the flags described


# Launch Go tests within a Cerbos context

cerbos run -- go test ./...

# Start Cerbos with a custom configuration file and run Python tests within the context

cerbos run --config=myconf.yaml -- python -m unittest

# Silence Cerbos log output

cerbos run --log-level=error -- curl -I

  <command> ...    Command to run

  -h, --help                                    Show context-sensitive help.

      --log-level="info"                        Log level (debug,info,warn,error)
      --config=./cerbos.yaml                    Path to config file
      --set=server.adminAPI.enabled=true,...    Config overrides
      --timeout=30s                             Cerbos startup timeout