Command line

coil compiles and runs Coil programs. Most projects drive it through spool, which adds the module roots and permission flags from coil.toml; this page is for running coil directly. coil --help and coil <command> --help print the complete, current list of options.

Flags go before the file: coil --root ../coil-stdlib/src -A app.hy. With a subcommand they go after it: coil compile --root ../coil-stdlib/src app.hy.

Commands#

Invocation	What it does
`coil <file.hy>`	Compile in memory and run. Nothing is written to disk.
`coil compile <file.hy> [-o path]`	Compile to a bytecode archive (`out.hyc` unless `-o`).
`coil run <file.hyc>`	Run a compiled archive. An archive from an incompatible runtime is rejected.
`coil package <file.hy> [-o path]`	Build a single executable for this OS and CPU (the `coil-embed` runner with the program inside).
`coil test [path]`	Run every test under `path` (default `./tests`) and the examples in `///` docs. See Test harness.
`coil verify <file.hy>`	Prove `requires` / `ensures` contracts with an SMT solver.
`coil mutate`	Mutation testing: which small edits to your code no test notices.
`coil fmt [--check] <file\|dir>…`	Format sources in place; `--check` only reports. Keeps `//` and `///` comments.
`coil lsp`	Start the language server on stdin/stdout, for editors.
`coil debug <file.hy>`	Interactive debugger (`--dap` for IDEs, `-x script --batch` for scripts).
`coil dissect <file.hy> [--fn name]`	Print the compiled bytecode of the matching functions.
`coil natives dump [exe]`	Print the native-library lock embedded in a packaged executable.
`coil -V`	Print the version.

Common flags#

Flag	Meaning
`--root DIR`	Add a directory that `use` paths resolve against (repeatable). The stdlib is one: `--root ~/.coil/stdlib/src`. See Modules.
`-A`, `--allow-read`, `--allow-write`, `--allow-net`, `--allow-env`, `--allow-exec`, `--allow-exit`, `--allow-attach`	Grant host access. A program gets none by default, and the compiler names the flag it is missing. See Permissions.
`--allow-dload STEM` with `--dload-pin STEM=SHA256` or `--dload-trusted STEM`	Allow loading a native library at run time. See Calling C.
`-O0` … `-O3`, `-Os`, `-Og`	Optimization level; `-O2` by default.
`-g0`, `-g1`, `-g2`	How much debug information to keep. `-g2` (the default) gives panics full locations and is needed by `coil debug` and coverage. `--strip-debug` is `-g0`.
`--contracts all\|requires\|off`	Which contract checks run.
`--comptime-read PATH`, `--comptime-net HOST`, …	What compile-time code may touch.

Examples#

# Run a file that uses the stdlib and reads files
coil --root ~/.coil/stdlib/src --allow-read wc.hy notes.txt

# Compile once, run many times
coil compile --root ~/.coil/stdlib/src app.hy -o app.hyc
coil run app.hyc

# Ship a single executable
coil package --root ~/.coil/stdlib/src app.hy -o app
./app

# Tests, formatting
coil test --root ~/.coil/stdlib/src tests
coil fmt --check src tests

Test blocks (test("…") { … }) are left out of coil compile and coil package output; pass --include-tests to keep them.

Toolkit binaries#

The release archive holds coil and the helpers it starts for some commands. Keep them in the same directory.

Binary	Used by
`coil-test`	`coil test`, `coil mutate`
`coil-fmt`	`coil fmt`
`coil-lsp`	`coil lsp`
`coil-debug`	`coil debug`
`coil-dissect`	`coil dissect`
`coil-embed`	`coil package` (the runner the program is embedded in)

Files#

Extension	Meaning
`.hy`	Coil source
`.hyc`	Compiled bytecode archive