CLI

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

Installation

pip install creed-space-cli

Requires Python 3.10+. To include the optional Guardian passthrough (pulls in the creed-guardian runtime):

pip install 'creed-space-cli[guardian]'

Publication gate: the [guardian] extra requires creed-guardian>=2.0. PyPI currently serves only the unsafe 0.1.1 preview, so this install will fail until creed-guardian 2.1.0 is published and verified. Install plain creed-space-cli until then.

Quick Start

# Validate any artifact — the type is auto-detected
creed validate my.creed.md
creed validate constitutions/ --format json

# Gate creed quality in CI
creed score my.creed.md --min-score 70

# Lint constitution source files against the schema
creed constitution lint constitutions/ --format json

# Validate and inspect VCP tokens and CSM1 codes
creed vcp validate family.safe.guide@1.0.0
creed vcp parse "Z4+P+T+W:SEC"

Commands

One command, five jobs:

Command	Purpose
creed validate <path|dir|token>...	Umbrella validator with artifact auto-detection (creeds, constitutions, VCP).
creed score <creed-file>...	Creed quality scoring and conflict detection, with a --min-score CI gate.
creed constitution lint <path|dir>...	Lint constitution source files against a bundled JSON schema plus structural rules.
creed vcp validate|parse <token-or-file>...	Validate or pretty-print VCP tokens, CSM1 codes, and VCP-Lite documents.
creed guardian <argv...>	Passthrough to the creed-guardian runtime.

All commands accept --format text|json. creed validate also takes --type (to override auto-detection), --strict (treat unrecognised inputs as failures) and --quiet. creed score takes --min-score.

Artifact detection

creed validate auto-detects what it's looking at:

• *.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 that can't be classified is an error — you meant to validate it — while an unrecognised file merely discovered while recursing a directory is skipped, so unrelated files don't break a run. --strict promotes every unknown to a failure; use it in CI when nothing should slip through unvalidated.

Exit codes

The contract your CI scripts can depend on — stable and documented:

Code	Meaning
0	Everything validated clean.
1	Findings — at least one artifact failed validation.
2	Usage error or missing input.
3	Internal or environment error (never a verdict about your files).

Drive gating logic off the exit code; parse the JSON summary for detail.

JSON output

--format json emits a stable, versioned document (schema_version: "1"): a per-artifact result list with typed findings and a summary block.

{
  "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.

Use in CI

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 constitutions/ --format json
      - name: Gate creed quality
        run: creed score creeds/*.creed.md --min-score 70

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: creed-validate
        name: creed validate
        entry: creed validate --strict
        language: system
        files: '\.(creed\.md|creed)$'

Guardian passthrough

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

creed guardian --help
creed guardian proxy --port 9090

If creed-guardian is not installed, the command prints an install hint and exits 2 rather than crashing.

Publication gate: the passthrough needs creed-guardian>=2.0, which is not yet on PyPI (see Installation).

Links

• creed-space-cli on PyPI
• vcp-sdk on PyPI — the SDK the VCP commands build on
• Value Context Protocol