#CLI reference

The complete molt command surface: every verb, its flags, its exit codes, and the cross-cutting rules that apply to all of them.

You install the distribution molt-cli and type the command molt. See Installation for why the two names differ.

#Command surface at a glance

#The default command

molt with no command word runs molt add. An option that belongs to add also works with no command word:

molt              # same as: molt add
molt --open       # same as: molt add --open

An explicit command is never overridden -- molt version runs version, not add.

#Global options

These options are accepted by every command (subject to the command actually having prompts, mutations, or machine-readable output to control).

The startup banner (molt v<version>, prefixed with a butterfly glyph) prints once before a matched command's output. It is not printed for --help or --version. On a Windows console that cannot encode the glyph, the banner degrades to plain text rather than raising an error.

-v is not a global alias for --version. On molt status, -v means --verbose. Use the long --version form for the version string.

#Machine-readable output

Molt produces a machine-readable plan object on every mutating command, and structured output on read commands:

• molt status and molt publish-plan accept --output json to print the plan as a JSON document to stdout.
• molt publish and molt git-tag accept --output <file> to write an NDJSON event stream -- one {"type":"git-tag", ...} object per line -- to a file.
• The MOLT_OUTPUT environment variable back-fills --output when the flag is not passed, so CI can set it once for the whole pipeline.

#Option-normalization rules

The same argument-handling rules apply across every command:

• Repeated scalar options: last wins. --since main --since next resolves to next, with no warning.
• Repeatable list options always yield a list, even for a single occurrence. This covers --major, --minor, --patch, --package, and --ignore.
• Numeric-looking values stay strings. --snapshot-name 123 is the string "123", so version and tag names that look numeric are never coerced to integers.
• Arguments after a bare -- are dropped. There is no pass-through.
• --snapshot takes an optional value through a small, documented divergence from changesets. Because the parser cannot bind a space-separated optional value, use --snapshot (unnamed), --snapshot=<name>, or --snapshot-name <name>. The space form --snapshot <name> is rejected with guidance. See molt version.

#Exit-code contract

On an unexpected internal error, molt prints a pre-filled issue-report URL that includes the CLI version and the Python version, with the working directory redacted to <cwd>, then exits 1. Any other uncaught exception prints a traceback and exits 1. molt never lets a bare traceback escape as the program's only output.

#See also

• The changesets model -- the add / version / publish loop these commands implement.
• The release plan -- the plan object that --dry-run and --output json expose.
• Dry runs and plans -- previewing any mutating command.
• Configuration -- the settings these commands read.