CLI

Look up all Presswork command families, arguments, options, help forms, output streams, color behavior, diagnostics, and exit status.

Presswork provides check, create, and skills command families. presswork --help or presswork -h displays generated root help, presswork --version or presswork -V displays the installed version, and presswork COMMAND --help or presswork COMMAND -h displays generated command-local help. Help and version requests exit 0. The CLI does not provide a help command, so presswork help COMMAND is an invalid invocation.

Calling presswork without a command is invalid. Unknown commands or options, missing option values, and excess arguments produce command-line parser output and exit 2. Parser error text uses standard error, while accompanying usage may use standard output. This output is not a Presswork diagnostic, and including --json does not convert it to JSON.

Repository Root selection

Without --root, Presswork discovers the nearest ancestor of the current directory whose .git marker is a file or directory. It does not follow a .git symbolic link. The selected Repository Root is reported as an absolute real path.

--root <path> selects one explicit Repository Root. Relative paths resolve from the current directory. An invalid explicit root never falls back to ancestor discovery.

Command summary

Command	Purpose
`presswork check [options]`	Validate repository documentation and write a Check Report.
`presswork create [options] [document-type]`	List Document Types or initialize one indexed Document Draft.
`presswork skills docs [options]`	Write one repository-specific `presswork-docs` Agent Skill.

`presswork check`

Use this syntax to select options for a Check.

presswork check [options]

Run a Check against the discovered Repository Root and write a human-readable Check Report.

presswork check

presswork check -h and presswork check --help display Check help without running a Check.

Options

Option	Meaning
`--root <path>`	Use one explicit Repository Root.
`--json`	Write the Check Report as one JSON object followed by a newline.
`--no-color`	Disable color in human output.

Human output starts with Check complete or Check incomplete. It reports the Repository Root, Profile, Markdown Dialect, Recognized Document count, Checked Document count, Violations, and Operational Diagnostics. Violations are grouped under their source document and include position, Rule identifier, message, relevant destination, optional Document Type, and recovery guidance.

Check Reports use standard output. Operational Diagnostics use standard error. An incomplete Check writes its retained Check Report to standard output and mirrors each Operational Diagnostic to standard error. A failure before a Check Report can be produced leaves standard output empty.

See Check Report for the JSON fields, ordering, and complete or incomplete semantics.

`presswork create`

Use this syntax to list Document Types or initialize one Document Draft.

presswork create [options] [document-type]

presswork create --help, presswork create -h, and presswork create DOCUMENT_TYPE --help display the same generated help without loading a Repository Root.

Options

Option	Meaning
`--list-types`	List repository Document Types with their Creation Policies.
`-f, --field <name=value>`	Supply one required creation field. Repeat the option for each field.
`--root <path>`	Use one explicit Repository Root.
`--json`	Write the catalog, successful result, or diagnostic as one JSON object followed by a newline.
`--no-color`	Disable color in human output.

--list-types cannot be combined with [document-type] or --field. The Basic Profile returns an empty catalog when the repository defines no Document Types.

Initialize a proposal Document Draft with its required slug and title fields.

presswork create proposal \
  --field slug=first-proposal \
  --field "title=First proposal"

A successful creation exits 0 and reports the created repository-relative path, updated Index Document, unfinished draft status, and pending Template requirements. It writes human or JSON output to standard output. Creation never overwrites an existing destination or chooses another filename.

An external Creation Policy reports the external owner workflow and refuses initialization. A manual policy explains that Presswork only validates and also refuses initialization. Invalid or missing fields, conflicts, refusals, and creation failures write one diagnostic to standard error, leave standard output empty, and exit 2.

`presswork skills docs`

Use this syntax to select an explicit Repository Root for skill rendering.

presswork skills docs [options]

Render the current repository’s validated policy as raw, complete SKILL.md bytes on standard output.

presswork skills docs

The only operational option for presswork skills docs is --root <path>. Use -h or --help for command-local help. The command does not accept --json or --no-color.

On success, the command exits 0 and writes only the raw, complete SKILL.md bytes to standard output. The output has no JSON wrapper, banner, progress, color, or unrelated logs.

Before rendering, Presswork resolves and validates the Repository Root, Presswork Configuration, Profile, Document Types, Templates, Creation Policies, Index Sections, and an operationally complete Check. Existing Violations do not block rendering. Discovery, configuration, Template, or operational failure writes one diagnostic to standard error, leaves standard output empty, and exits 2.

Run presswork skills without a subcommand, or use presswork skills -h or presswork skills --help, to display family help and exit 0. Use presswork skills docs -h or presswork skills docs --help for docs help. These forms display generated help without loading a Repository Root.

JSON, color, and streams

For check and create, --json selects machine-readable operational output. Each JSON value is one object followed by a newline. Presswork diagnostics also use one JSON object per line when --json is present. Command-line parser errors remain text rather than JSON.

Color is optional decoration in human output and carries no meaning. It is omitted for JSON, redirected output, --no-color, and a non-empty NO_COLOR environment variable. Normal command output uses standard output. Diagnostics use standard error.

The nested skills docs command is the exception to these shared presentation options: it accepts only --root and writes raw SKILL.md.

Exit status

Exit	Meaning
`0`	Help or version succeeded, creation or catalog listing succeeded, skill guidance rendered, or a Check completed with no Violations.
`1`	A Check completed and found one or more Violations.
`2`	Invalid invocation, Repository Root, configuration, operational, creation, skill-rendering, or internal failure prevented success. Incomplete Checks also exit `2`.
`130`	`SIGINT` or `SIGTERM` interrupted active work. Presswork exits without writing a diagnostic.

Diagnostic codes

Code	Command family	Meaning
`repository-root-not-found`	Repository commands	No Repository Root could be discovered.
`invalid-repository-root`	Repository commands	An explicit root is not a valid Repository Root.
`repository-root-unavailable`	Repository commands	Presswork could not inspect the selected root.
`configuration-unavailable`	Repository commands	Present Presswork Configuration could not be read.
`invalid-configuration`	Repository commands	Present Presswork Configuration does not satisfy its strict contract.
`document-type-unknown`	`create`	The requested Document Type is not configured.
`document-type-creation-external`	`create`	The Document Type delegates creation to a named external workflow.
`document-type-creation-manual`	`create`	The Document Type requires manual creation.
`document-creation-field-invalid`	`create`	A supplied field name, value, or `name=value` pair is invalid.
`document-creation-preflight-failed`	`create`	Template, index, temporary-directory, or mutation-path preflight failed.
`document-creation-conflict`	`create`	Another writer or existing destination prevented exclusive creation.
`document-creation-index-stale`	`create`	The Index Document changed before publication.
`document-creation-recovery-required`	`create`	The Index update failed and the created draft was preserved for review.
`document-creation-unavailable`	`create`	A required Template or filesystem operation was unavailable.
`skill-guidance-unavailable`	`skills docs`	Repository-specific guidance could not validate or load required policy.
`internal-error`	All	An unexpected internal failure reached the CLI boundary.

Presswork diagnostics include a stable code, message, and recovery guidance. Path-related diagnostics also include path. Human diagnostics use labeled lines; --json writes one diagnostic object followed by a newline for commands that accept it. Command-line parser output is not part of this diagnostic contract. Public diagnostics omit internal causes and stacks.

The three Check Report Operational Diagnostic codes are cataloged in Check Report. An incomplete Check mirrors those diagnostics to standard error.

See Rules for the distinction between Rules and diagnostic codes, Check Report for report data, or Concepts for how the command contracts fit the Presswork model.