Project Management

Zamin ships with a full CLI toolchain for creating, running, formatting, and testing projects. This page covers every command and the project manifest format.

CLI Commands

Command	Description
zamin run <file> [--disassemble]	Run a Zamin source file. Pass --disassemble to print the bytecode before execution.
zamin repl	Start the interactive Read-Eval-Print Loop.
zamin version	Print the Zamin version, build date, and LLVM version.
zamin fmt <file>	Format a Zamin source file in place.
zamin test [filter]	Run all tests, or only tests matching filter.
zamin new <name>	Scaffold a new project directory with the standard layout.
zamin init	Initialize a zamin.json manifest in the current directory.
zamin build	Build the project into a standalone executable.
zamin-rs <file>	Quick runner - compiles and executes a single file in one step.

Project Structure

Create a new project with:

zamin new my_project

This generates the following layout:

my_project/
├── zamin.json
├── src/
│   └── main.zamin
├── tests/
│   └── main_test.zamin
└── modules/

You can also initialize a manifest in an existing directory:

mkdir my_project && cd my_project
zamin init

zamin.json Manifest

The zamin.json file describes your project. Here is the full format with all supported fields:

{
  "name": "my_project",
  "version": "1.0.0",
  "description": "A short description of the project.",
  "author": "Your Name",
  "license": "MIT",
  "entry": "src/main.zamin",
  "dependencies": {
    "http": "^1.0.0",
    "json": "^2.1.0"
  },
  "dev_dependencies": {
    "test_utils": "^0.5.0"
  },
  "scripts": {
    "start": "zamin run src/main.zamin",
    "test": "zamin test",
    "fmt": "zamin fmt src/"
  },
  "modules_path": "modules/",
  "target": "linux-x86_64",
  "optimization": "release"
}

Field	Type	Description
name	string	Project name
version	string	Semantic version
description	string	Short description
author	string	Author name
license	string	License identifier (SPDX)
entry	string	Entry point file (default: src/main.zamin)
dependencies	object	Runtime dependencies
dev_dependencies	object	Development-only dependencies
scripts	object	Named scripts runnable with zamin run --script <name>
modules_path	string	Path to load native modules from (default: modules/)
target	string	Build target triple
optimization	string	"debug" or "release"

REPL

Start the interactive REPL with:

zamin repl

The REPL supports the following built-in commands:

Command	Description
exit	Exit the REPL
help	Show available commands and shortcuts
history	Print the command history for the current session

Tab Completion

Press Tab to auto-complete keywords, built-in functions, and previously used identifiers. Press Tab twice to see all possible completions.

Formatter

Zamin includes a built-in code formatter. Use it to enforce consistent style:

zamin fmt src/main.zamin

You can also format all files in a directory:

zamin fmt src/

The formatter is idempotent - running it multiple times produces the same output. It respects existing indentation and does not reorder imports.

Testing

Zamin has a built-in test framework. Write tests using the test module:

use test

func test_addition() {
    test.assert_eq(1 + 1, 2, "1 + 1 should equal 2");
    test.assert(2 + 2 == 4, "2 + 2 should equal 4");
}

func test_string_reverse() {
    let input = "hello";
    let reversed = input.reverse();
    test.assert_eq(reversed, "olleh", "reverse of 'hello' is 'olleh'");
}

func test_error_handling() {
    test.assert_raises(func() {
        let x = nil;
        x.value();
    }, "accessing nil should raise an error");
}

Run your tests with:

zamin test

Run only tests whose names match a filter:

zamin test addition

This will run only test_addition. The filter is matched as a substring against all test function names.