@promptc/cli

@promptc/cli

The promptc command — a deterministic, LM-free compiler for prompts.

promptc parses a prompt in Markdown, XML, or plain text, runs a fixed sequence of optimization passes over the resulting IR, and emits the optimized prompt back into the chosen surface format. The compile path never calls a language model, never consults a learned model, and produces bit-for-bit reproducible output for any fixed input.

Reader-facing docs:

• Quickstart — 5-minute tutorial.
• Passes — per-pass preconditions, postconditions, behavior-preservation arguments.
• IR — the typed PromptIR for library consumers.
• Comparisons — placement vs SAMMO, DSPy, LLMLingua, ctxray.
• DESIGN.md — the full design contract.
• examples/ — five runnable prompts, one per pass.

Install

Runtime: the published CLI runs on Node.js >=20. This repository uses Bun for local workspace orchestration and tests, but users do not need Bun to run the npm package.

npm install --save-dev @promptc/cli

Or run with npx (no install):

npx --yes @promptc/cli optimize --target=cost --in prompt.md

Subcommands

optimize — run the full pass pipeline

promptc optimize --target=cost --in prompt.md --out prompt.opt.md

Flags:

flag	values	default	meaning
--target	cost, tokens, none	cost	optimization profile
--in <path>	path to input file	stdin	input prompt source
--out <path>	path to output file	stdout	optimized prompt destination
--from <fmt>	markdown, xml, plain	inferred	source surface format
--to <fmt>	markdown, xml, plain	same as --from	target surface format
--passes a,b,c	comma-separated pass names	full pipeline	explicit pass order
--max-mutations <n>	integer	unlimited	hard cap on node mutations

Examples:

# Optimize a markdown prompt, write back to markdown:
promptc optimize --target=cost --in prompt.md --out prompt.opt.md

# Optimize and convert from markdown to XML:
promptc optimize --target=cost --in prompt.md --to=xml --out prompt.opt.xml

# Streaming via stdin/stdout:
cat prompt.md | promptc optimize --target=cost --from=markdown > prompt.opt.md

# Run only specific passes, in this order:
promptc optimize --target=cost \
  --passes=dead_instruction_elimination,whitespace_redundancy_strip \
  --in prompt.md

A per-pass summary is printed to stderr so it does not interfere with the optimized prompt on stdout:

promptc optimize: markdown -> markdown  (target=cost)
  pass dead_instruction_elimination         skipped (no-op)  [no dead instructions found]
  pass example_pruning_by_mutual_info       skipped (no-op)  [no redundant examples above threshold]
  pass format_collapse                      skipped (no-op)  [no candidate rewrite produced a strictly shorter equivalent]
  pass whitespace_redundancy_strip          applied -11 tok
  pass vocab_simplification                 skipped (no-op)  [no verbose phrases matched]
tokens: 141 -> 130  (-11, -7.8%)
bytes:  860 -> 829

parse — print the IR for a prompt

promptc parse --in prompt.md
promptc parse --in prompt.md --pretty   # (default)
promptc parse --in prompt.md --no-pretty

Prints the typed PromptIR as JSON on stdout. Useful for diffing, snapshotting, or piping into downstream tools.

passes — list available passes

promptc passes

dead_instruction_elimination              Drop instructions not referenced by output schema, examples, or peers.
example_pruning_by_mutual_info            Drop few-shot examples redundant by token-overlap with retained peers.
format_collapse                           Collapse verbose markdown/XML formatting where whitespace-insensitive.
whitespace_redundancy_strip               Trim trailing whitespace, collapse blank-line runs, strip filler openers.
vocab_simplification                      Rewrite verbose phrases to short equivalents from a curated map.

explain — dry-run a single pass

promptc explain --in prompt.md --pass=whitespace_redundancy_strip

Outputs the pass's description, precondition status, and a dry-run result (no IR or file is modified). Useful for understanding why a pass did or did not fire on a given prompt:

# Pass: whitespace_redundancy_strip

Description: Trim trailing whitespace, collapse blank-line runs, strip filler openers.

Preconditions: ok

Dry-run result:
  applied: true
  droppedTokens (approx): 11
  debug:
    sectionsChanged: 4
    instructionsChanged: 0
    bytesSaved: 11

version

promptc version

Exit codes

code	meaning
0	success
1	input error (bad flags, missing file, unreadable bytes, bad subcommand)
2	IR validation error (parsed IR or post-pass IR violates an invariant)
3	explicitly-requested pass failed preconditions or is not implemented

stdout carries the optimized prompt (or IR JSON for parse, or help text otherwise). stderr carries summaries, diagnostics, and error messages. This split makes the CLI safe to compose in shell pipelines.

Determinism

Same input bytes + same pass selection + same compiler version produces the same output bytes. The pipeline does not call any LM, does not consult any trained model, does not read the clock or any RNG state, and only reads input from the path or stdin the user supplied.