rcas command reference

rcas is the Rule Cascade command: it checks, compiles and evaluates rulesets, serves the engine protocol to other languages, scaffolds projects, derives rules from API schemas, finds rules in existing code, and serves the Model Context Protocol to AI coding tools. One static binary for Linux, macOS and Windows (x86-64 and ARM64), and rcas.wasm for any WASI host.

The install scripts and go install also provide it as rule-cascade (its earlier name): the same binary, which then names itself rule-cascade in its messages. The npm package provides rcas only, so that npx -y @rules-cascade/cli <command> knows which command to run.

Invocation

rcas [-C <dir>] [--config <rcas.yaml>] [--no-color] <command> [arguments]
rcas help <command>          rcas <command> --help

Flags may come before or after file arguments, --flag=value works, and -- ends the flags.

Global options

The project file is the first rcas.yaml, rcas.yml or rcas.json found in the working directory or above it. Its format is in project configuration; every environment variable is in environment variables.

Exit codes

Command map

init

rcas init [dir] [--name <name>] [--id-prefix <prefix>] [--lang ts,python,java,go,other] [--from <path>]
          [--agent claude,codex,cursor,copilot,gemini|all] [--mcp <client>|all] [--ci github|none] [--force] [--dry-run]

What gets created:

rcas init --name "Acme Payments" --lang ts,java --agent all --mcp claude

check and test

rcas check [file|dir]... [--json]
rcas test  [file|dir]... [--json]

For each ruleset: validates it against the schema, loads it (inheritance, override policies, the static checks of the specification), reports YAML and numbers that are not portable, checks OpenAPI bindings, and runs its golden tests with the conformance operators. Without arguments, every ruleset under rules.dir of rcas.yaml; a directory means every *.ruleset.* file under it.

$ rcas check
acme.payments.example@0.1.0  sha256:ebacd52bdbea...  2 rules (2 client-safe), 1 params
  3 golden tests, 0 failed

Exit status 1 when any file has a problem or a failing test.

compile

rcas compile <file> [-o out.bundle.json]
rcas compile --all [-o <dir>]

Compiles a ruleset into a bundle: plain JSON, checksummed, loaded by every runtime without YAML or schema validation. With --all, every ruleset of the project into output.dir (default build/rules) as <id>.bundle.json, and <id>.<channel>.manifest.json for each channel in output.manifests. A bundle holds server-only rules: deploy it to backends, never to browsers.

manifest

rcas manifest <ruleset-or-bundle> | --bundle <bundle.json> | --manifest <manifest.json> [--channel client|server] [-o out.manifest.json]

Prints or writes one manifest. The default channel is client (what a browser or app may receive), or the channel of the manifest given.

evaluate

rcas evaluate --bundle <bundle.json> | --manifest <manifest.json> [--channel server|client] [--conformance-operators] [request.json|-]

Evaluates one request, read from a file or standard input (-, the default), and prints the result: decision, findings, effects, commands. The default channel is the server's.

echo '{"entity":"Order","operation":"create","data":{"quantity":11}}' | rcas evaluate --bundle build/rules/acme.payments.example.bundle.json -

engine

rcas engine [--conformance-operators]

Serves the engine protocol of specification section 13 on standard input and output: one JSON request per line, one JSON response per line. This is how a language without a native runtime (C#, Rust, PHP, Ruby, Swift, C++ ...) evaluates: start it once as a child process. --conformance-operators registers the operators the conformance suite uses.

analyze

rcas analyze [path] [--format md|json] [-o <file>] [--derive] [--include <glob>]... [--exclude <glob>]... [--max-files <n>]

Inventories a code base for rule extraction: API schemas (OpenAPI 3, JSON Schema) with their schema names, and decisions in code with file:line: Zod, Joi, Yup, class-validator, Pydantic, marshmallow, Django validators, Bean Validation, Spring validators, Go validate: tags, ozzo-validation, FluentValidation, data annotations, Rails, Laravel, the Rust validator crate, rule engines in use, and hand-written checks that throw or return a validation error. It reads and never runs code, and skips dependencies and build output.

A hit is a candidate, not a rule: what it decides is for a person or an agent reading the code.

derive

rcas derive <openapi.yaml|schema.json> --id <ruleset.id> [--schema <Name> | --pointer </$defs/X>] [--entity <Name>]
            [--scope level:id]... [--version <v>] [--title <t>] [--tests <file>] [--codes-from <file>] [-o <file>] [--check] [--propose]

Builds a validation ruleset from the constraints of a schema: required members, types, enums, lengths, patterns, ranges, item counts. What cannot be expressed is listed on standard error, not guessed. The output is deterministic and identical to the reference implementation.

Details of the mapping: OpenAPI.

proposals

rcas proposals list [--status pending|invalid|accepted|rejected] [--json]
rcas proposals show <id> [--diff] [--json]
rcas proposals accept <id> [--force]
rcas proposals reject <id> [--reason <text>]

A proposal is one or more ruleset files that an AI agent (through rcas mcp) or derive --propose / analyze --derive suggested. It waits in .rcas/proposals/ with its rationale, its sources and the problems check found. A proposal holds only ruleset and schema files (*.ruleset.yaml, .yml, .json, *.schema.json) under the rules directory. accept writes the files into the project; it refuses when a target file changed after the proposal was made, or when the proposal does not pass check (invalid); --force overrides both. Accepting is the only way a proposal reaches the rules.

mcp

rcas mcp [--root <dir>] [--read-only] [--list-tools]

Serves the Model Context Protocol on standard input and output. AI coding tools start it; see the tools and the safety model in MCP server.

mcp install

rcas mcp install <claude|codex|cursor|windsurf|gemini|vscode|all>... [--scope project|user] [--print] [--file]
                 [--command npx|binary] [--name <name>] [--force]

Other settings and servers in the file are kept. A file with comments is not changed: add the printed entry by hand.

agent install

rcas agent install [--for claude,codex,cursor,copilot,gemini|all] [--print] [--force] [--dry-run]

Managed blocks (between rcas:begin and rcas:end) are replaced on every run; the rest of those files is kept. Other files are written when missing, or with --force.

doctor

rcas doctor [--json]

Checks the command (version, PATH, a newer release unless RCAS_NO_NETWORK is set), the project (rcas.yaml, every ruleset passes check, .rcas/ ignored, proposals waiting), the MCP configuration of every AI tool it knows, and the agent instructions. Exit status 1 when a check fails; warnings do not fail.

completion

rcas completion bash|zsh|fish|powershell

version

rcas version [--json]

$ rcas version
rcas 1.0.0-alpha.5 (specification 1.0.0, bundle format 1.0.0)