Skip to content

CLI reference

The polychro CLI is the single entry point for linting documents and serving the Polychro MCP tools. It ships as a runnable JAR / native image; see Installation for how to get it on your PATH.

This page is a complete reference: every command, every option, every exit code that the binary exposes. For walkthroughs, see Getting started and the Guides.

Synopsis

polychro [-hV] <command> [options] [arguments]

Global options

Option Description
-h, --help Show help and exit. Available on every command.
-V, --version Print the Polychro version and exit.

Command catalog

Command Purpose
lint Lint one or more YAML / JSON / XML / Markdown / HTML files.
serve Start an MCP server exposing Polychro linting tools.

Running polychro without a subcommand prints the usage banner.

polychro lint

Run the Polychro pipeline on one or more files and emit diagnostics in the selected format.

polychro lint [options] <file> [<file> ...]

Arguments

Argument Description
<file> Required, one or more. Files to lint. Format is auto-detected from the content (YAML / JSON / XML / Markdown / HTML).

Options

Option Description
-f, --format <text\|json\|sarif\|agent> Output format. Default: text.
• text — human-readable text.
• json — machine-readable diagnostics.
• sarif — SARIF 2.1.0 for CI/static-analysis integrations.
• agent — compact, agent-optimized output.
-v, --validators <list> Comma-separated list of validators to enable. When omitted, the default validator stack runs.
-r, --ruleset <path> Path to a custom ruleset file. Combine with the built-in rulesets via --config.
-s, --schema <path> Path to a custom schema file. Applied to both the json-schema and json-structure validators.
--default-schema-validator <json-schema\|json-structure> Default schema-model validator used when a document does not declare a $schema. Default: json-schema.
-c, --config <path> Path to a .polychro.yml configuration file. When provided, takes precedence over the inline flags above.
-h, --help Show help and exit.

Built-in rulesets

Rulesets can be passed by name (resolved against the bundled ruleset registry, e.g. polychro:ai-safety, polychro:governance, polychro:security) or as a path to a custom ruleset file via --ruleset. See Guide: Rulesets for the full catalog and tag taxonomy.

Ruleset filtering (--tags, --exclude-tags) is currently driven through the configuration file rather than CLI flags — see Guide: Configuration.

Examples

# Default pipeline, text output
polychro lint my-spec.yml

# AI-safety ruleset, agent-friendly output
polychro lint -r polychro:ai-safety -f agent my-spec.yml

# SARIF for GitHub Code Scanning
polychro lint -f sarif specs/ > results.sarif

# Validate against a custom JSON Schema
polychro lint --schema my-schema.json my-spec.yml

# Use a project configuration file
polychro lint --config .polychro.yml specs/

# Disable schema validation, run only the structural validator
polychro lint --default-schema-validator json-structure my-spec.yml

Exit codes

Code Meaning
0 No diagnostics found.
1 Warnings only (no errors).
2 One or more errors found, or the command itself failed (missing file, parse error, invalid config, unhandled exception).

polychro serve

Start an MCP (Model Context Protocol) server that exposes Polychro's linting capability to agent runtimes. See Guide: MCP server for how to wire the server into Claude Desktop, Cursor, and other MCP clients.

polychro serve [options]

Options

Option Description
-c, --config <path> Path to a .polychro.yml configuration file used by the server.
-h, --help Show help and exit.

Examples

polychro serve
polychro serve --config .polychro.yml

Exit codes

Code Meaning
0 Server started and shut down cleanly.
2 Configuration file not found, or the MCP server failed to start.

Configuration file precedence

When --config is provided, the configuration file is the source of truth for validator selection, ruleset selection, tag filters, and per-validator settings. The inline flags (--validators, --ruleset, --schema, --default-schema-validator) are only used when --config is not provided. See Guide: Configuration for the complete schema.

Exit-code conventions

Code Meaning
0 Success / no findings.
1 lint only — warnings but no errors.
2 Errors found, or an unexpected exception was thrown. The CLI prints Error: <message> to stderr before exiting.

See also