Skip to content
Molto

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.