Reference
4 min read
CLI Reference
Warning
Most users interact with StateAnchor through the GitHub Action. The Action authenticates via GitHub OIDC, runs the full gate pipeline against the prior snapshot, and annotates PRs automatically -- no local install or token management required. See the GitHub Action reference for the full interface.
stateanchor check is a local YAML validator only -- it does not call the StateAnchor API, does not require authentication, and does not compare against a prior snapshot.stateanchor check
Local, rule-based validation of your stateanchor.yaml configuration file. Runs 17 structural rules and outputs findings in ERR / WARN / INFO lanes. No network call. No authentication required.
Usage
Flags
| Flag | Default | Description |
|---|---|---|
--config <path> | ./stateanchor.yaml | Path to the config file to validate |
--fail-on <level> | err | Exit non-zero when findings reach this lane. Options: err, warn, none |
--json | off | Emit findings as JSON array (CI-friendly) |
Exit codes
| Code | Meaning |
|---|---|
0 | No findings at or above --fail-on threshold |
1 | Findings found at or above --fail-on threshold |
2 | Config file not found or invalid YAML |
Example output
What it checks -- 17 rules
| Code | Lane | Description |
|---|---|---|
MISSING_SERVICE | ERR | service field missing or empty |
MISSING_VERSION | ERR | version field missing |
MISSING_SERVER | ERR | server block missing |
MISSING_BASE_URL | ERR | server.base_url missing |
BASE_URL_NOT_HTTP | WARN | server.base_url does not start with http:// or https:// |
INVALID_AUTH_TYPE | ERR | server.auth.type is not one of: bearer, api_key, basic, oauth2, none |
AUTH_MISSING_TYPE | WARN | server.auth block present but type is missing |
NO_ENDPOINTS | ERR | endpoints array is missing or empty |
ENDPOINT_MISSING_NAME | ERR | An endpoint entry is missing name |
ENDPOINT_MISSING_METHOD | ERR | An endpoint entry is missing method |
ENDPOINT_INVALID_METHOD | ERR | An endpoint’s method is not a valid HTTP verb |
ENDPOINT_MISSING_PATH | ERR | An endpoint entry is missing path |
PATH_NO_LEADING_SLASH | WARN | An endpoint’s path does not start with / |
DUPLICATE_ENDPOINT_NAME | ERR | Two endpoints share the same name |
DUPLICATE_ENDPOINT_SIGNATURE | WARN | Two endpoints share the same method + path |
UNKNOWN_LANGUAGE | WARN | outputs.languages contains an unsupported language |
NO_OUTPUTS | INFO | No outputs block -- no SDK artifacts will be generated on sync |
Pre-push hook
Add to .git/hooks/pre-push to catch ERR findings before every push. Make the file executable with chmod +x .git/hooks/pre-push.
Note
Limitations -- static schema validation only.
stateanchor check does not fetch or compare against the prior API snapshot, does not run the full drift detection pipeline (lib/spec-diff.js), and does not evaluate gate score or blocking conditions based on drift. Full gate evaluation requires the GitHub Action or dashboard sync.Next:GitHub Action →