CLI reference¶

moonlit¶

moonlit [-V | --version] [-h | --help] <subcommand> [args...]

Top-level flags¶

Running moonlit with no subcommand and no flag prints the help to stderr and exits 2. Running moonlit <unknown> (with or without --help) prints error: no such subcommand: <name> to stderr and exits 2.

Subcommands: build (produce a .pyz/.exe from a local uv project), pack (produce one straight from PyPI packages — no project needed), info (inspect a built archive's env.json), and clean (reap stale cache entries).

moonlit build¶

moonlit build [PROJECT] -e <entry> | -c <script> -o <output> [flags]

PROJECT is an optional positional that defaults to the current working directory. It must resolve to an existing directory.

Flags¶

Flag interactions¶

• Exactly one of -e / -c is required. Neither or both → exit 2.
• -q and -v are mutually exclusive → exit 2.
• --no-dev and --dev are mutually exclusive → exit 2.
• --package is required iff the project is a uv workspace → exit 5 on mismatch.
• --windows-exe (without --bundle-python) requires --output-file to end in .exe (case-insensitive) → exit 2.
• --python-version must match ^\d+\.\d+$ (major.minor only) → exit 2.
• --bundle-python rejects --output-file values ending in .exe or .pyz → exit 2. With --bundle-python the output is a directory; the directory's basename is reused for the launcher and inner zipapp filenames inside.
• When --windows-exe AND --python-version are set AND -p is at its default, the default shebang pivots from python.exe to py -<X.Y> so the recipient's PEP 397 launcher pins to the matching interpreter.
• The MOONLIT_* environment variables are runtime-only; they are ignored during a build.

Preflight order¶

The CLI performs these checks in order; the first failure short-circuits with the listed exit code. The order is part of the contract — tests pin which fault wins on multi-fault inputs.

1. Click argument parsing (unknown flag, missing -o, both/neither of -e/-c, -q+-v, --no-dev+--dev) → exit 2.
2. PROJECT resolves to an existing directory → exit 2.
3. uv on PATH (shutil.which("uv")) → exit 3.
4. <PROJECT>/pyproject.toml exists → exit 5.
5. <PROJECT>/uv.lock exists → exit 4.
6. Workspace shape vs --package → exit 5.
7. --entry-point syntactic validity → exit 6.
8. Output-path preflight → exit 7.
9. Build pipeline → exits 6, 8, 9, 10.

Exit codes¶

Build-time and runtime exit codes are independent enumerations; the runtime codes (0–3) live in Runtime. The same numeric value can mean different things in the two namespaces.

stdout / stderr semantics¶

• Default: progress lines go to stderr — one line per pipeline step with a brief result and elapsed time (e.g. writing archive · wrote myapp.pyz · 1.3s total). The final line wrote <output> (<size>, <N> entries) goes to stdout.
• --quiet: stderr is suppressed; the stdout success line is preserved.
• --verbose: on error, the full traceback follows the error line on stderr.
• Errors: every error is a single line on stderr, formatted as <ErrorClassName>: <message>. With --quiet, errors are still emitted.
• Parser-level errors: formatted as error: <message> (lowercase error:), distinct from the class-prefixed format used for MoonlitError subclasses.

Examples¶

Build a single-package project, current directory:

moonlit build -e myapp.cli:main -o myapp.pyz

Build a workspace member, with a custom shebang:

moonlit build /path/to/workspace --package shouter \
    -e shouter.cli:main \
    -p '/usr/bin/env python3.13' \
    -o shouter.pyz

Resolve the entry point from a console script declared by the target's wheel:

moonlit build --package myapp -c myapp -o myapp.pyz

Overwrite an existing output file:

moonlit build -e myapp.cli:main -o myapp.pyz --force

Get a traceback when something goes wrong:

moonlit build -e myapp.cli:main -o myapp.pyz -v

Cross-compile a .pyz for Python 3.12 from a Python 3.13 dev box (uv auto-fetches a managed CPython 3.12 if needed):

moonlit build --python-version 3.12 -e myapp.cli:main -o myapp-py312.pyz

Produce a native Windows .exe pinned to Python 3.12 (shebang auto-pivots to py -3.12):

moonlit build --windows-exe --python-version 3.12 -e myapp.cli:main -o myapp.exe

Produce a fully self-contained folder bundle that ships a managed CPython next to a thin launcher .exe so recipients don't need Python installed:

moonlit build --bundle-python --python-version 3.12 \
    -e myapp.cli:main -o dist/myapp

The bundle directory layout:

dist/myapp/
├── myapp.exe       # the launcher (runs ./_python/python.exe ./myapp.pyz)
├── myapp.pyz       # the application zipapp
└── _python/        # bundled CPython tree (~30 MiB)

Distribute the folder (typically by zipping it) and run myapp\myapp.exe. The folder-bundle shape replaces the v0.3.0 single-.exe --bundle-python output, which tripped Windows Defender's ML heuristics for self-extracting archives. The new shape extracts nothing at runtime and so isn't flagged.

moonlit pack¶

moonlit pack [SPEC] [--with SPEC ...] [-r FILE ...] -e <entry> | -c <script> -o <output> [flags]

Build a .pyz/.exe/folder-bundle directly from PyPI requirement specs — with no local pyproject.toml or uv.lock. This is the moonlit analogue of uvx --with <extra> <tool> or shiv -e mod:fn <pkgs>: hand it package names, get back a self-contained artifact a recipient can run with neither uv nor PyPI access. moonlit build stays the command for your own uv-managed project; pack is for bundling things that already live on an index.

pack resolves the full dependency closure at build time with uv pip compile — that resolution is the lock for the produced artifact (there is no uv.lock to freeze). It then installs the closure with uv pip install --no-deps and runs the same back half as build (entry-point resolution → build_id → env.json → archive). There is no uv build wheel step — every package, including the primary one, is just a resolved dependency.

SPEC is an optional positional — the primary package in PEP 508 form (mooring, mooring==1.4, mooring[extra]>=1). It seeds both the default name and the default entry point.

Flags¶

* Exactly one of -e/-c is required — except when a positional SPEC is present and you pass neither, in which case pack defaults to -c <name-from-SPEC> (resolve the console script named after the primary package, exactly as uvx <tool> would run it).

pack does not accept --package, --dev, or --no-dev — there is no workspace and no dependency groups.

Flag interactions¶

• At least one of SPEC, --with, --with-requirements must be present → else exit 2.
• --name is required when there is no positional SPEC → else exit 2.
• Both -e and -c → exit 2; neither (with no SPEC to default from) → exit 2.
• -q+-v, the --windows-exe/--bundle-python suffix rules, and --python-version format are validated exactly as for build.

Exit codes¶

Same enumeration as build, with one addition: a uv pip compile failure (e.g. an unsatisfiable resolution) is exit 8 (CompileError) — the same resolution-failure code build uses for ExportError. The install (9), entry-point (6), output (7), and bundled-Python (13) codes are shared with build unchanged.

Determinism note¶

Because there is no uv.lock, pack resolves fresh each time. Two packs of the same specs against a moved index may pick newer pins and therefore a different build_id (and a different cache key on recipients). If you need frozen, reproducible inputs, pin exact versions in your specs or pass a fully-pinned --with-requirements file.

Examples¶

Bundle a PyPI tool plus an extra dependency (the uvx --with polars mooring case), then run it offline:

moonlit pack mooring --with polars -o mooring.pyz
python mooring.pyz        # runs mooring's console script, polars bundled in

Pick the entry point explicitly instead of the console-script default:

moonlit pack mooring --with polars -e mooring.cli:main -o mooring.pyz

Bundle straight from an existing requirements file (shiv-style):

moonlit pack --with-requirements requirements.txt --name mooring -c mooring -o mooring.pyz

Pin a version and cross-compile for Python 3.12:

moonlit pack "mooring==1.4" --python-version 3.12 -o mooring-py312.pyz

moonlit info¶

moonlit info <pyz> [--json]

Print the env.json manifest of a moonlit-built archive. <pyz> must resolve to an existing regular file.

Default output: a one-line header <path> (<size>, <N> entries) followed by a sorted listing of the manifest's required fields (build_id, built_at, entry_point, moonlit_version, name, python_shebang, schema_version). The optional python_version field is not included in the default listing today; use --json to see it.

If the input is not a zipfile, or env.json is missing/malformed, exit 12 with BadArchiveError: <reason> on stderr.

Examples:

moonlit info myapp.pyz
moonlit info myapp.pyz --json | jq .python_version

moonlit clean¶

moonlit clean [flags]

Reap stale cache entries from the runtime cache root. The cache root is resolved the same way the bootstrap resolves it: MOONLIT_ROOT if set, otherwise %LOCALAPPDATA%\moonlit\ on Windows or ~/.moonlit/ on POSIX.

Every .pyz extracts its bundled site-packages/ to <cache_root>/<normalized_name>_<build_id>/site-packages/ on first run. By default, artifacts also self-prune their own app's older entries automatically (keep newest N, default 2 — see Runtime → Automatic cache cleanup and --gc), so a single app's footprint is bounded without moonlit clean. moonlit clean remains the tool for cross-app reaping, whole-cache wipes, age- or name-filtered sweeps, and orphan cleanup — and for trimming caches left by artifacts that were built with --no-gc.

Flags¶

Bare moonlit clean (no --all, no --older-than, no --keep-latest, no --name) exits 2 with a usage message. There is no implicit "scan and report" default — that would tempt a "do nothing" mental model.

When more than one of --all, --older-than, --keep-latest, --name is set, the deletion set is the intersection. --keep-latest is applied last, after the other filters narrow the candidate set.

Output¶

The action plan is rendered as a table on stderr with columns ACTION, NAME, BUILD_ID, AGE, SIZE, PATH. The trailer is one line on stdout:

deleted N entries, freed <bytes_humanized>

--dry-run swaps the trailer to would delete N entries, would free … and leaves the filesystem alone. --quiet suppresses the table but the trailer stays on stdout.

ACTION is one of:

• delete — the entry will be removed (or was removed, in a real run).
• keep — within a --keep-latest group, this is one of the N newest.
• skip — a candidate that could not be deleted (its <cache_key>.lock is held and --force was not set). The reason appears in parentheses after the path.
• orphan — a .tmp.<pid>/.old.<pid>/.lock sibling reaped because its owning cache_key is missing or being deleted.

Liveness model¶

moonlit clean is cooperative. For each cache entry slated for deletion it tries to acquire <cache_key>.lock non-blocking. On success it holds the lock through the rmtree, so a concurrent extractor serializes against the deletion. On failure the entry is marked skip (locked); the process exit code is 14 to signal partial completion.

The bootstrap's cache-hit fast path reads site-packages/ without holding the lock. moonlit clean therefore cannot detect a process that is mid-import. Do not run moonlit clean while a moonlit .pyz is actively in use. This is documented in specs/CROSS_CUTTING_DECISIONS.md D23.

--force bypasses the try-lock entirely. The cache directory is deleted regardless of lock state; the lock file is left in place (a live holder still owns the byte range on Windows and we do not pull the rug). The next clean run will reap the lock file once nothing holds it.

Exit codes¶

Examples¶

Preview what --all would delete without touching the filesystem:

moonlit clean --all --dry-run

Reap cache entries older than 30 days:

moonlit clean --older-than 30d

Keep the 3 newest builds per app, delete the rest:

moonlit clean --name '*' --keep-latest 3

Delete only myapp cache entries:

moonlit clean --name myapp

Force-delete a stuck cache (e.g. after a debugger killed an extracting process and left a stale lock):

moonlit clean --all --force

python -m moonlit¶

python -m moonlit ... is equivalent to moonlit ...; both delegate to the same moonlit.cli.main(). Useful when the moonlit console script isn't on PATH but moonlit is importable.