Skip to content

CLI reference

This is the authoritative CLI reference for incan (commands, flags, paths, and environment variables).

No-install fallback

If you did not run make install, you can still run the incan binary directly:

  • from the repository root:
./target/release/incan ...
  • or via an absolute path (from anywhere):
/absolute/path/to/incan run path/to/file.incn

Usage

Top-level usage:

incan [OPTIONS] [FILE] [COMMAND]
  • If you pass a FILE without a subcommand, incan type-checks it (default action).

Commands:

  • build - Compile to Rust and build an executable
  • run - Compile and run a program
  • fmt - Format Incan source files
  • test - Run tests (pytest-style)

Global options (debug)

These flags take a file and run a debug pipeline stage:

incan --lex path/to/file.incn
incan --parse path/to/file.incn
incan --check path/to/file.incn
incan --emit-rust path/to/file.incn

Strict mode:

incan --strict --emit-rust path/to/file.incn

Commands

incan build

Usage:

incan build <FILE> [OUTPUT_DIR]

Behavior:

  • Prints the generated Rust project path (example): target/incan/<name>/
  • Builds the generated Rust project and prints the binary path (example): target/incan/<name>/target/release/<name>

Example:

incan build examples/simple/hello.incn

incan run

Usage:

incan run [OPTIONS] [FILE]

Run a file:

incan run path/to/file.incn

Run inline code:

incan run -c "import this"

incan fmt

Usage:

incan fmt [OPTIONS] [PATH]

Examples:

# Format files in place
incan fmt .

# Check formatting without modifying (CI mode)
incan fmt --check .

# Show what would change without modifying files
incan fmt --diff path/to/file.incn

incan test

Usage:

incan test [OPTIONS] [PATH]

Examples:

# Run all tests in a directory
incan test tests/

# Run all tests under a path (default: .)
incan test .

# Filter tests by keyword expression
incan test -k "addition"

# Verbose output (include timing)
incan test -v

# Stop on first failure
incan test -x

# Include slow tests
incan test --slow

Outputs and paths

Build outputs:

  • Generated Rust project: target/incan/<name>/
  • Built binary: target/incan/<name>/target/release/<name>

Cleaning:

rm -rf target/incan/

Environment variables

  • INCAN_STDLIB: override the stdlib directory (usually auto-detected; set only if detection fails).
  • INCAN_FANCY_ERRORS: enable “fancy” diagnostics rendering (presence-based; output may change).
  • INCAN_EMIT_SERVICE=1: toggle codegen emit mode (internal/debug; not stable).

Exit codes

General rule: success is exit code 0; errors are non-zero.

Specific behavior:

  • incan run: returns the program’s exit code.
  • incan test:
    • returns 0 if all tests pass
    • returns 0 if test files exist but no tests are collected
    • returns 1 if no test files are discovered under the provided path
    • returns 1 if any tests fail or an xfail unexpectedly passes (XPASS)
  • incan fmt --check: returns 1 if any files would be reformatted.
  • incan build / incan --check / debug flags: return 1 on compile/build errors.

Drift prevention (maintainers)

Before a release, verify the docs stay aligned with the real CLI surface:

  • Compare incan --help and incan {build,run,fmt,test} --help against this page.