The commands
Every subcommand, the flags it takes, the exit code it returns and what it prints to a terminal or a pipe — the same on Linux, Windows and macOS.
Every command finds your project by walking up from the current directory, so all of them work from any subdirectory. They behave the same on Linux, Windows and macOS: one binary per platform, the same flags, the same exit codes, the same output.
| Command | Options |
|---|---|
molto new <name> |
--lib (default), --bin |
molto init |
--lib (default), --bin |
molto build |
-p/--profile, -t/--target, --refresh-toolchain, -j/--jobs |
molto run [-- args] |
-p/--profile, --refresh-toolchain, -j/--jobs |
molto test [-- args] |
-p/--profile, --refresh-toolchain, -j/--jobs |
molto clean |
-a/--all |
molto fmt |
-c/--check, -d/--diff, --refresh-tools, --refresh-analysis, -j |
molto lint |
-p/--profile, -f/--format, --refresh-toolchain, --refresh-tools, --refresh-analysis, -j |
molto add <dep>[@<version>] · git+<url>[#<ref>] |
-d/--dev, --git, --path, --archive, --registry |
molto remove <dep> |
— |
molto metadata |
-o/--output, --include-dev |
molto ir |
-o/--output, -p/--profile |
molto login |
-r/--registry, -e/--email, -t/--token |
molto publish |
--recipe, -f/--file, -p/--pack, --dry-run |
molto plugin <list|info|install|remove> [name] |
-r/--registry, -y/--yes |
molto bench, molto migrate and molto update exist in the CLI and exit 5: the command is
recognised, the behaviour is not implemented. update stays that way on purpose —
molto add <name> is the upgrade, the way npm install is.
The parser accepts --opt value, --opt=value, -o value and boolean flags. Everything after
-- is forwarded to the program under molto run, and to the test executables under
molto test. --help and --version come for free.
Starting a project
molto new my_lib # a static library, tested with moltest (the default)
molto new my_app --bin # a program with a src/main.c
molto init # either of the two, in the directory you are already in
--lib writes include/<name>.h, src/<name>.c, a test under tests/, and a manifest with
artifact = "static", [test] mode = "single" and moltest
in [dev-deps] — pinned to its newest release, asked of its repository (offline, the newest release
Molto knows). --bin writes src/main.c and the manifest. Neither ever overwrites a file that
already exists, and neither initialises git.
Building and running
molto build # into build/debug/
molto build -p release # into build/release/
molto build --target <triple> # for another platform, into build/<triple>/debug/
molto run -- --flag value # build, run, and forward everything after --
molto test # build and run the tests
molto test --profile coverage # the same, instrumented for coverage
Profiles: debug (the default), release, bench, custom and coverage. See
the manifest for what each one sets.
molto run propagates the program’s own exit code verbatim; on Linux and macOS it reports
128 + N when the program dies from signal N. That is the one command whose exit code is not
Molto’s. On a library (artifact = "static" or "shared") it refuses before building anything:
there is nothing to run, and molto test is what exercises it.
-j <n> caps the worker pool; absent means every core. It is refused unless it is a count between
1 and 1024, and it is never recorded or fingerprinted — two builds differing only in -j produce
the same objects.
Output layout
| Path | Contents |
|---|---|
build/<profile>/<package> |
The executable (<package>.exe on Windows) |
build/<profile>/lib<package>.a |
A static library |
build/<profile>/lib<package>.so.X.Y.Z |
A shared library on Linux; lib<package>.X.Y.Z.dylib on macOS |
build/<profile>/obj/src/**/*.c.o |
Intermediate objects |
build/<profile>/tests/<name> |
One test executable per file (per_file) |
build/<profile>/tests/<package>_tests |
The single test executable (single) |
build/<triple>/<profile>/… |
The same layout, for a --target build |
.bin/wsdb |
Incremental state and the cached toolchain answer |
compile_commands.json |
The compilation database, at the project root |
Molto.lock |
The resolved dependency graph |
build/ and .bin/ belong to Molto and are gitignored. Molto.lock is generated and
committed. molto clean removes build/; molto clean --all also removes .bin/. Neither
touches the shared cache described below.
compile_commands.json is written by a build, and the last one wins: molto build covers
src/ plus dependencies, molto test covers those and tests/, and -p release leaves a
database describing release. fmt and lint write none. It is written even when the build fails.
Testing
molto test # every test, in the mode the manifest names
molto test -- -k parser # arguments after -- reach the test executables
molto test --profile coverage # instrumented; moltest_coverage prints the report
molto test --profile custom # e.g. sanitizers, from [profile.custom].flags
By default (per_file) each file under tests/ is its own executable, linked against the
project’s objects minus src/main.c. With a framework that owns main(), such as moltest,
mode = "single" links everything into one. A [[test.isolated]] file is linked alone, without
the sources it replaces, so a fake can stand in for them. Every executable is told its place in
the run through MOLTO_TEST_INDEX (from 1) and MOLTO_TEST_COUNT, which is how a coverage report
knows the last one has finished. The details are in the manifest.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Build failure; fmt --check found unformatted files; lint produced an error |
| 2 | Invalid manifest or invalid configuration |
| 3 | Dependency failure |
| 4 | Usage error |
| 5 | The command exists but is not implemented |
| 6 | A plugin failed |
A lint warning is reported and still exits 0. Only error severity fails the command.
What a build prints
Everything goes to stderr, so molto build > log still shows the build and molto run > out
captures only your program.
On a terminal it draws an inventory, then a live region, and takes the region away when the work stops:
◆ registry sqlite v3.53.4
◇ modules network
● project 62 files
○ cached 20 files
● project services/build_service.c
◆ sqlite sqlite3.c
… and 5 more
████████░░░░░░░░ 22% 47/210
A dependency gets one line however many sources it has — a package is one piece of work.
Nothing already up to date is listed; it is counted on cached, so a no-op rebuild is three lines
and no region.
Redirect stderr — a pipe, a file, a CI job — and you get one line per source, no region, no
bar, and not one escape sequence. That is the full record, and it is what CI should keep.
NO_COLOR=1 removes the colour on a terminal but not the region, which is about motion. The
cursor is never hidden, so Ctrl-C leaves the terminal as it found it.
A failing unit is reported in a frame carrying the source line, a caret under the character the
tool named, and a footer saying whose code it was. A whole diagnostic is composed and handed to
the report in one call, so two workers can never interleave. A build that fails prints no
Finished line.
Where Molto keeps its files
| What | Linux and macOS | Windows |
|---|---|---|
| The registry credential | ~/.config/molto |
%APPDATA%\molto |
| Installed plugins | ~/.local/share/molto |
%APPDATA%\molto |
| Sources, objects, platform files | ~/.cache/molto |
%APPDATA%\molto\cache |
On Linux and macOS the three follow $XDG_CONFIG_HOME, $XDG_DATA_HOME and $XDG_CACHE_HOME.
MOLTO_HOME puts everything in one directory instead, and MOLTO_CACHE moves the cache alone. A
~/.molto left by an older Molto is migrated the first time a newer one runs.
Environment variables
| Variable | Effect |
|---|---|
MOLTO_PICKUP |
Path to the pickup binary when it is not on the PATH |
C_COMPILER |
Forces the C driver — skips pickup and skips requires verification |
CPP_COMPILER |
Forces the C++ driver, same caveat |
MOLTO_CLANG_FORMAT |
Path to the formatter; bypasses resolution, not cached |
MOLTO_CLANG_TIDY |
Path to the linter; same |
MOLTO_HOME |
One directory for everything Molto keeps, instead of the platform’s |
MOLTO_CACHE |
The shared cache alone |
MOLTO_PKG_CONFIG |
The pkg-config asked about [target].host libraries and platform packages |
MOLTO_ZSTD |
The zstd that unpacks platform packages (fetched on Windows when absent) |
NO_COLOR |
Turns colour off on a terminal |
Molto prints a warning to stderr when C_COMPILER is used, because a compiler chosen by hand was
never checked against [target].requires.
Where pickup comes in
Molto does not choose a compiler. A manifest states the capabilities the code needs; pickup answers which local binary provides them, and the answer is cached in the workspace database — the question is asked once rather than on every build.
pickup list # every toolchain on this machine
pickup doctor # what stops this machine from building, and what fixes it
pickup install clang
pickup tools # the formatter and the linter, and where they are
If pickup resolve reports a runtime_dirs for a toolchain it installed, what Molto links
carries the -rpath in itself, so a binary keeps running wherever it goes.
Platforms
| Platform | Status |
|---|---|
| Linux | The gate: the suite, a self-hosted build, four compiler and optimisation combinations, sanitizers, a static binary |
| Windows | Supported since 2026-09-04: src/ and tests/ compile, Molto builds a project, builds itself, and passes its suite on a Windows runner |
| macOS (arm64) | Supported since 2026-09-05, by the same four measures, on an arm64 macOS runner |
Every release publishes a binary for each of the three, and each one is exercised on the platform
it is for before it is published — see Install and platforms. A project needs
nothing per platform: the same Project.toml builds on all three.