Metadata-Version: 2.4
Name: creed-space-cli
Version: 0.1.0
Summary: Creed Space CLI — validate creeds, constitutions, and VCP tokens
Project-URL: Homepage, https://valuecontextprotocol.org
Project-URL: Repository, https://github.com/Creed-Space/creedspace
Author-email: Creed Space <hello@creed.space>
License-Expression: Apache-2.0
Keywords: ai,alignment,cli,creed,ethics,safety,values,vcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4
Requires-Dist: pyyaml>=6
Requires-Dist: vcp-sdk>=0.3
Provides-Extra: guardian
Requires-Dist: creed-guardian>=2.0; extra == 'guardian'
Description-Content-Type: text/markdown

# creed-space-cli

`creed` is a command-line validator for [Creed Space](https://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

```bash
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. Unknown inputs are reported as
`skipped` (and become findings under `--strict`). Pass `--type` to override
detection.

### Exit codes

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

| Code | Meaning |
|------|---------|
| `0`  | all inputs valid |
| `1`  | validation findings (at least one artifact failed) |
| `2`  | usage error / missing input |
| `3`  | internal error |

`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"`):

```json
{
  "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`](https://pypi.org/project/creed-guardian/) runtime:

```bash
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

```yaml
# .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

```yaml
# .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](../docs/CREED_GUARDIAN_QUICKSTART.md) — the
  local safety runtime behind `creed guardian`.
