CLI Commands

Complete reference for all nicc commands and options.

Global Options

These options work with any command:

nicc --version    # Print version info
nicc --help       # Show help
nicc -h           # Show help (short form)

nicc build

Build a project from nic.toml:

nicc build [OPTIONS]

Options

Option	Description
-o, --output FILE	Output file (default: project name)
--release	Build with optimizations
-a, --ast	Show parsed AST
-s, --sast	Show typed AST (SAST)
-v	Increase SAST verbosity (use with --sast)
-l, --llvm	Show LLVM IR
-d, --debug	Enable parser tracing
--trace-log FILE	Write parser trace to file
--error-format FORMAT	Error output format: pretty or json
--no-color	Disable colored output

Examples

# Basic build
nicc build

# Build with custom output name
nicc build -o myprogram

# Release build with optimizations
nicc build --release

# Inspect generated LLVM IR
nicc build --llvm

# Debug build with detailed type info
nicc build --sast -vv

nicc run

Build and run a project or file:

nicc run [OPTIONS] [FILE] [-- ARGS...]

Options

Option	Description
-b, --build	Compile to binary (default: JIT)
-k, --keep	Keep compiled binary after execution
--release	Build with optimizations
All inspection options from build	--ast, --sast, etc.

Modes

JIT Mode (default): Compiles to memory and executes immediately. Fastest for development.

nicc run                  # Run project
nicc run file.nic         # Run single file
nicc run -- arg1 arg2     # Pass arguments to program

Native Mode: Compiles to a binary, then executes it.

nicc run --build              # Compile and run
nicc run --build --keep       # Keep the binary afterward
nicc run --build --release    # Optimized native compilation

Examples

# Run project with arguments
nicc run -- --verbose input.txt

# Run single file, show LLVM IR
nicc run --llvm test.nic

# Compile and keep binary for profiling
nicc run --build --keep --release

nicc new

Create a new project:

nicc new <NAME> [OPTIONS]

Options

Option	Description
--path PATH	Project directory (default: ./<name>)

Generated Files

nicc new myproject

Creates:

myproject/
├── nic.toml      # Project manifest
└── src/
    └── main.nic  # Entry point

Example nic.toml

[project]
name = "myproject"
version = "0.1.0"

[paths]
src = "src/"

[prelude]
enabled = true

nicc init

Initialize a project in the current directory:

nicc init

Creates nic.toml and src/main.nic if they don't exist. Useful for adding Nic to an existing directory.

nicc lsp

Start the Language Server Protocol server:

nicc lsp [OPTIONS]

Options

Option	Description
--log FILE	Log file for debugging

The LSP server communicates via stdin/stdout and is typically started by your editor automatically. See Editor Support (LSP) for setup instructions.

nicc bindgen

Generate Nic bindings from C header files:

nicc bindgen <HEADER> [OPTIONS]

Options

Option	Description
-o FILE	Output file (default: stdout)
-I PATH	Include path for clang (repeatable)

Examples

# Generate bindings to stdout
nicc bindgen mylib.h

# Generate to file with include paths
nicc bindgen sqlite3.h -o sqlite3.nic -I/usr/include

# Multiple include paths
nicc bindgen raylib.h -I/opt/raylib/include -I/usr/local/include

See C Bindings (bindgen) for details on type mappings and usage.

Single-File Mode (Legacy)

Compile a single file without a project:

nicc [OPTIONS] <FILE>

Options

Option	Description
-a, --ast	Print parsed AST
-s, --sast	Print typed SAST
-v	Increase SAST verbosity
-l, --llvm	Print generated LLVM IR
-c, --compile	Compile to executable
-o FILE	Output file (default: a.out)
-d, --debug	Enable parser tracing
--trace-log FILE	Parser trace output file
--error-format FORMAT	pretty or json
--no-color	Disable colors

Examples

# Show AST
nicc --ast hello.nic

# Show typed AST with full type annotations
nicc --sast -vv hello.nic

# Compile to executable
nicc -c -o hello hello.nic
./hello

# Debug parser issues
nicc --debug --trace-log trace.txt --ast broken.nic

Exit Codes

Code	Meaning
0	Success
1	Compilation error (parse, type, or codegen)
Other	Runtime error from executed program

See Also

• Project Configuration - nic.toml format
• Debugging - Debug flags and tracing
• Editor Support (LSP) - IDE integration