creed-space-cli

creed is a command-line validator for Creed Space artifacts: creeds, constitutions, and VCP tokens. It runs locally and in CI, needs no authentication, and speaks JSON for machine consumption. Think terraform validate or gh, but for values declarations.

Install

pip install creed-space-cli

# With the optional guardian passthrough (pulls in the creed-guardian runtime):
pip install creed-space-cli[guardian]

Requires Python 3.10+. Inside the Creed Space monorepo it is available as python -m creed_cli (or poetry run creed) without a separate install; from a source checkout, pip install ./vcp-sdk-python ./creed_cli.

Command surface

creed --version
creed --help
creed validate <path|dir|string>...  [--type auto|creed|constitution|vcp-lite|vcp-token|csm1]
                                      [--format text|json] [--strict] [--quiet]
creed score <creed-file>...          [--min-score N] [--format text|json]
creed vcp validate <token-or-file>   # VCP token / CSM1 code / VCP-Lite JSON (auto-detected)
creed vcp parse <token-or-csm1>      # pretty-print the parsed structure
creed constitution lint <path|dir>... [--format text|json]
creed guardian <argv...>             # passthrough to the creed-guardian runtime

validate is the umbrella command. It auto-detects artifact type:

• *.creed.md / *.creed → creed
• .json / .yaml matching the constitution shape, or files under a constitutions/ directory → constitution
• vcp:-prefixed or CSM1-patterned strings, and .vcp files → VCP

Directories recurse over known extensions. An input you name explicitly on the command line that can't be classified is an error (exit 1) — you meant to validate it. An unrecognised file merely discovered while recursing a directory is skipped, so unrelated files (READMEs, configs) don't break a run. --strict promotes every unknown, discovered or not, to a failure — use it in CI when you want nothing to slip through unvalidated. Pass --type to override detection.

Exit codes

Every command uses the same convention (also printed in creed --help):

creed guardian preserves the exit code of the underlying creed-guardian process, so guardian's own status codes propagate unchanged.

JSON output contract

--format json emits a stable, versioned document (schema version "1"):

{
  "schema_version": "1",
  "results": [
    {
      "path": "data/constitutions/_source/example.yaml",
      "artifact_type": "constitution",
      "status": "failed",
      "findings": [
        {"severity": "error", "code": "SCHEMA",
         "message": "...", "location": "$.rules[3]"}
      ]
    }
  ],
  "summary": {"checked": 12, "passed": 11, "failed": 1, "skipped": 0}
}

• status is one of passed, failed, skipped.
• severity is error or warning; code is a stable machine token.
• Parse the top-level summary for a quick pass/fail count; drive gating logic off the process exit code.

Guardian passthrough

creed guardian <argv...> forwards every argument verbatim to the creed-guardian runtime:

creed guardian --help          # prints creed-guardian's help
creed guardian proxy --port 9090
creed guardian serve
creed guardian mcp

If creed-guardian is not installed, creed guardian prints an install hint (pip install creed-space-cli[guardian]) and exits 2 rather than crashing.

CI recipes

GitHub Actions

# .github/workflows/creed-validate.yml
name: creed validate
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install creed-space-cli
      - name: Validate constitutions
        run: creed constitution lint data/constitutions/_source --format json
      - name: Gate creed quality
        run: creed score creeds/*.creed.md --min-score 70

The step fails the job automatically when creed exits non-zero.

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: creed-validate
        name: creed validate
        entry: creed validate
        language: python
        additional_dependencies: ["creed-space-cli"]
        files: '\.(creed\.md|creed)$|constitutions/.*\.(json|ya?ml)$'
        pass_filenames: true

pass_filenames: true hands the staged, matching files to creed validate; the commit is blocked when validation reports findings.

Related

• docs/CREED_CLI.md — architecture and design overview.
• Creed Guardian Quick Start — the local safety runtime behind creed guardian.