CLI

Look up Presswork commands, arguments, options, help, output streams, color, and exit status.

Presswork provides check, create, and skills command families. Use -h, --help for root help and -V, --version for the installed version. presswork help COMMAND displays help for a command. Help and version requests exit 0.

Calling presswork without a command is invalid. Unknown commands or options, missing option values, and excess arguments write an invalid-invocation diagnostic to standard error and exit 2.

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

presswork check

Run a Check against the discovered Repository Root:

presswork check

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

Options

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

The exact command syntax uses an optional [document-type] operand:

presswork create [options] [document-type]

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

Options

List available Document Types before creating a draft:

presswork create --list-types

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

For a Document Type with a presswork Creation Policy, repeat -f or --field for every required input:

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

Render repository-specific skill guidance:

presswork skills docs

The only operational option for presswork skills docs is --root <path>. Commander help remains available through -h and --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.

Use presswork skills -h, presswork skills --help, or presswork help skills for family help. Use presswork skills docs -h, presswork skills docs --help, or presswork skills help docs for docs help. These forms display static help without loading a Repository Root.

JSON, color, and streams

For check and create, --json selects machine-readable output. Each JSON value is one object followed by a newline. Diagnostics also use one JSON object per line when --json is present.

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

Expected diagnostics include a stable code, message, recovery guidance, and a relevant path when applicable. They do not expose caught causes, stack traces, or dependency error detail.

See Glossary for the canonical domain terms used by command output and this reference.