Skip to main content
Forge is the official build tool for Kairo projects. It manages dependencies, compiles your source code, runs your test suite, and prepares packages for distribution. Every Forge command operates on the project rooted at the current working directory unless you pass an explicit path. This page is the complete reference for all Forge commands, their outputs, and the diagnostic code system.

​
forge restore

Resolves all dependencies declared in your project manifest and writes a forge.lock file that pins exact versions for reproducible builds.
What it does:
  • Reads your project manifest (kairo.toml) for declared dependencies.
  • Resolves the full transitive dependency graph.
  • Writes forge.lock with pinned version information.
  • Downloads any packages not already present in the local cache.
Outputs:
  • forge.lock — generated or updated in the project root.
Commit forge.lock to source control for applications. Libraries can optionally omit it, but pinning is recommended for reproducibility.

​
forge check

Validates your source code and reports diagnostics without producing any build artifacts. Use this for fast feedback during development.
What it does:
  • Parses and type-checks all .ak source files.
  • Emits diagnostics (errors and warnings) to the terminal.
  • Exits with a non-zero code when errors are found.
Outputs:
  • Diagnostic messages only — no files are written to build/ or .forge/.
Run forge check in your editor’s save hook or CI pipeline for fast feedback. It is significantly faster than forge build because it skips code generation.

​
forge build

Runs the full compilation pipeline: parsing, type-checking, and artifact generation. Use this when you need deployable output.
What it does:
  • Performs everything forge check does.
  • Generates compiled artifacts into build/.
  • Writes the build plan, output manifest, and IR handoff files to .forge/.
Outputs:
  • build/ — compiled application artifacts.
  • .forge/ — Forge-internal metadata consumed by the Pulse runtime.
forge build implicitly runs dependency resolution if forge.lock is missing or out of date. Run forge restore explicitly before forge build in clean CI environments to keep the two steps distinct.

​
forge test

Discovers and runs the project’s test suite.
What it does:
  • Builds the project (if needed) or uses cached artifacts.
  • Discovers test declarations in the source tree.
  • Runs all tests and reports pass/fail results.
  • Exits with a non-zero code when any test fails.
Outputs:
  • Test result summary to the terminal.
  • Exit code 0 for all-pass; non-zero for any failure.

​
forge package

Packages the compiled project for distribution, producing a distributable archive ready for publishing.
What it does:
  • Verifies the build is up to date (triggers forge build if necessary).
  • Bundles compiled artifacts, manifest, and metadata into a distribution package.
  • Writes the package to the build/ directory.
Outputs:
  • A distributable package archive under build/.

​
forge publish

Publishes the packaged project to the Kairo package registry.
What it does:
  • Runs forge package if the package is not already prepared.
  • Authenticates with the configured registry.
  • Uploads the package and registers the new version.
Publishing is irreversible — once a version is published to the registry, it cannot be deleted or overwritten. Always verify the version number in kairo.toml before running forge publish.

​
forge clean

Removes all generated build output and Forge-internal metadata. Source files are never touched.
What it does:
  • Deletes the build/ directory.
  • Deletes the .forge/ directory.
  • Does not remove source files, kairo.toml, or forge.lock.
Outputs:
  • A clean project directory with only source and configuration files remaining.
forge clean is safe to run at any time. It will never modify or delete your .ak source files, your manifest, or your lock file.

​
Diagnostic Code Prefixes

Forge and the Pulse runtime emit structured diagnostic codes. Each code has a three-letter prefix that identifies its origin, followed by a numeric identifier. Example diagnostics:

​
Build Output Layout

After a successful forge build, your project directory contains the following generated structure:
Add build/ and .forge/ to your .gitignore. Both directories are fully reproducible from source via forge restore && forge build.