Below is a comprehensive documentation draft for the saw command-line interface, written as user-facing docs rather than a help dump.

The saw Command Line Interface

The saw CLI is the primary tool for working with Axe projects. It handles project initialization, building, running, testing, dependency management, and inspection. Most day-to-day development workflows are performed through saw.

A typical invocation looks like:

saw <command> [options]

Commands define the action to perform, while options and flags modify how that action is executed.

Project Lifecycle Commands

init

saw init

Initializes a new Axe project in the current directory. This command creates the basic project structure, including configuration files and default source layout. It is intended to be run once at the start of a project.

After initialization, the directory is ready to be built, run, and extended with dependencies.

build

saw build [flags]

Builds the current project. This command invokes the Axe compiler and produces the final build artifacts without executing them.

By default, the build is performed in debug mode unless overridden by flags. Build outputs are placed in the project’s build directory.

run

saw run [flags]

Builds the project and immediately runs the resulting executable. This is equivalent to running saw build followed by executing the output binary, but ensures the binary is always up to date.

This command is typically used during development for quick iteration.

check

saw check
saw check <file>
saw check --all

Checks the project for compilation errors without producing build artifacts.

When run without arguments, saw check validates the main project entry points. Providing a file checks only that specific source file. The --all flag forces a full project-wide check.

This command is useful for fast feedback during development and editor integrations.

test

saw test
saw test <module>
saw test [flags]

Runs tests defined in the project.

If no module is specified, all tests are executed. When a module name is provided, only tests belonging to that module are run. Build flags may be passed to control optimization and debug behavior.

Tests are compiled and executed in an isolated test context.

clean

saw clean

Removes all build artifacts generated by previous builds. This includes compiled binaries and intermediate files.

Cleaning the project is useful when switching build modes, diagnosing build issues, or reclaiming disk space.

info

saw info

Displays information about the current project. This typically includes project name, version, build configuration, dependencies, and relevant paths.

This command is intended for inspection and debugging of project configuration.

Dependency Management Commands

add

saw add <url>

Adds a new dependency to the project from a git repository URL. The dependency is recorded in the project configuration and will be fetched during installation.

Dependencies added this way are treated as source-based dependencies and are integrated into the build process.

remove

saw remove <name>

Removes a dependency by name from the project configuration. This does not automatically delete downloaded files but ensures the dependency is no longer used during builds.

install

saw install

Installs all dependencies listed in the project configuration. This command fetches missing dependencies and prepares them for use by the compiler.

It is commonly run after cloning a project or modifying dependency declarations.

Global Help and Version

help

saw help
saw -h

Displays a summary of available commands and options. This is equivalent to invoking saw without arguments.

version

saw --version
saw -v

Prints the version of the saw tool currently installed.

Build Flags

Several flags modify how build-related commands behave. These flags can be used with build, run, test, and other commands that invoke the compiler.

--release

Builds the project with optimizations enabled. This mode is intended for production builds and prioritizes performance.

--debug

Builds the project with debug symbols enabled. This mode is useful for debugging and development tooling.

In addition to these, saw forwards most compiler-specific flags directly to the Axe compiler. This allows advanced users to fine-tune compilation behavior without changing the CLI.

Typical Workflow

A common development workflow with saw looks like this:

Initialize a project with saw init
Add dependencies using saw add
Install dependencies with saw install
Build and run during development using saw run
Run tests with saw test
Create optimized builds using saw build --release

The saw CLI is designed to remain minimal while exposing the full power of the Axe compiler and ecosystem.

Repo: saw