Skip to content

CLI reference

The Verdict CLI (verdict) provides two sets of tools:

  • Local policy and runtime commands for validating, testing, and formatting .vd policy files (validate, test, fmt) or running local processes (serve, lsp) without an external server.
  • Server commands that connect to a running Verdict instance to inspect health (status), publish or read policies (policy), manage stored facts (fact), check permissions (authorize), and evaluate predicates (query).

This reference covers the non-PostgreSQL commands available in the current checkout. Run verdict --version to check your installed CLI version and verdict commands --json to inspect the full command catalog.

verdict status --local --json
verdict authorize User:alice read Document:handbook --local --json

The authorize command above connects to a local server (http://localhost:4891) and checks whether User:alice is allowed to "read" Document:handbook. When access is permitted, it prints {"allowed":true} and exits with status 0. When access is denied, it prints {} and exits with status 1.

Commands

Section titled “Commands”
TaskReference
Inspect installed commandscommands, describe, search
Check a serverstatus
Check permissions and evaluate predicatesauthorize, query
Read or replace the active policypolicy
Read and change stored factsfact
Manage instance connectionsprofile, config show, configuration
Validate, test, and format policy filesvalidate, test, fmt
Start local processesserve, lsp

Pass --help (or -h) to any command or group to view its arguments and flags without executing the operation. Command groups (policy, fact, profile, config) require a subcommand.

  • authorize vs. authorise: authorize is the canonical command name; authorise is supported as an alias. Command aliases are listed on their canonical reference page.
  • fact list vs. query: fact list inspects only directly stored facts. query evaluates your policy rules as well as stored facts, returning bound values for each wildcard position in request order.

Output and exit status

Section titled “Output and exit status”

Human-readable and JSON output

Section titled “Human-readable and JSON output”

By default, finite commands print human-readable records to stdout. Passing --json writes a single JSON document to stdout instead.

Each generated command page documents its exact JSON result schema:

  • Commands backed by ProtoJSON projection omit default-valued fields (for example, an authorize denial omits "allowed": false and outputs {}).
  • fact and query commands encode integers as decimal strings.
  • Streaming and raw-output commands do not emit a finite --json result: fmt writes formatted policy source (or formatting check records), serve runs in the foreground until shut down, and lsp reserves stdout for Language Server Protocol messages.

Retrieve a policy

Section titled “Retrieve a policy”

policy get retrieves the original published source, including comments, whitespace, and line endings. It prints exact source without an added newline. Use verdict policy get > policy.vd to save it to a file.

With --json, the command returns { "source": "..." } followed by a newline. It does not return compiled rules. Empty published source is valid and returns an empty string in either format.

If source is unavailable, the command fails with exit status 1 and a republish instruction in either format. JSON errors use the standard structured error format.

Exit status and errors

Section titled “Exit status and errors”

If you are scripting the CLI in shell pipelines or CI workflows, pay close attention to how exit status 1 is used:

  • Exit status 0 means the command completed and its check succeeded (for example, authorize allowed access, test passed all assertions, or validate found no diagnostics).
  • Exit status 1 is returned for negative domain outcomes (such as a denied authorize decision, a failed test assertion, a validate error diagnostic, or an unformatted file in fmt --check) as well as for operational failures (such as invalid CLI arguments, file I/O errors, or an unreachable server).

Returning status 1 on denial or failed checks lets shell scripts branch directly on the command’s exit code (if verdict authorize ...; then), while the output format distinguishes a normal negative outcome from an operational error:

  • Negative domain outcome (status 1): Retains the command’s normal output on stdout (such as {} for a denied authorize --json check, or the test report for test --json).
  • Operational failure (status 1): Without --json, the CLI runner writes the error message to stderr. With --json, the runner writes {"error":{"code":"...","message":"..."}} to stdout, where code is one of invalid-arguments, io-error, server-error, unavailable, or internal-error.

Check the individual command page for command-specific exit status details.

Section titled “Related guides”