Skip to main content
Forge is the all-in-one tool for working with Kairo packages. It acts as compiler, build system, package manager, and publish pipeline in a single CLI. Every operation Forge performs follows the same deterministic, manifest-driven pipeline — starting from kairo.toml, resolving the dependency graph from forge.lock, collecting source files, and producing well-structured output in build/. Whether you are iterating on a library or shipping an application to production, Forge is the tool you reach for.

​
Command overview

​
Commands in detail

​
forge restore

Resolves the dependency graph declared in [dependencies] and writes forge.lock. Run this command whenever you add, remove, or change a dependency in kairo.toml. All other Forge commands read from the lockfile, so forge.lock must be up to date before you build.
Forge does not search parent directories for a kairo.toml in v0.1. Run all Forge commands from the package root (the directory containing kairo.toml) or the workspace root (the directory containing workspace.toml).

​
forge check

Runs every stage of the build pipeline up to — but not including — artifact generation. Forge validates your manifest, restores dependencies from forge.lock, collects source files, lexes and parses them, performs semantic analysis, and runs the type checker. If any stage produces a diagnostic at error severity, Forge reports it and stops. No files are written to build/. Because forge check produces no output artifacts, it is fast and safe to run frequently. Use it as your tight feedback loop while writing code.
Run forge check on every save or as a pre-commit hook. It gives you the same diagnostic quality as a full build without the overhead of code generation.

​
forge build

Runs the full build pipeline from manifest loading through to output writing. Forge loads your manifest, restores from forge.lock, collects and parses all source, performs semantic analysis and type checking, plans artifact output, runs code generation, and writes the final artifacts and metadata to build/. The complete pipeline in order:
1

Manifest loading

Forge reads and validates kairo.toml.
2

Dependency restore

Forge reads forge.lock and resolves the full dependency graph.
3

Source collection

Forge discovers all .ak source files under src/.
4

Lexing

Source text is tokenised.
5

Parsing

Token streams are parsed into ASTs.
6

Semantic analysis

Module declarations, name bindings, and scope rules are validated.
7

Type checking

All expressions and declarations are type-checked.
8

Artifact planning

Forge determines what output files to produce and where.
9

Code generation

Forge generates runtime artifacts and metadata.
10

Output writing

Final artifacts are written to build/.

​
forge test

Compiles the project and the test suite under tests/, then runs all discovered tests. Diagnostics from test compilation are reported the same way as production source diagnostics.

​
forge package

Builds the project (equivalent to forge build) and then bundles the resulting artifacts, metadata, and any declared resources into a distributable package archive. Run this before forge publish or when you want to inspect the exact artifact set that would be published.

​
forge publish

Packages the project and uploads it to the Kairo package registry. Publishing a version is irreversible — once a version is published, its content is immutable. Increment your version in kairo.toml before running forge publish for every new release.
Published package versions cannot be changed or deleted. Always verify your package with forge package and test it thoroughly before publishing.

​
forge clean

Deletes the build/ and .forge/ directories, removing all compiled artifacts and cached intermediate data. Use forge clean when you need a completely fresh build state. forge clean never touches:
  • Source files under src/, tests/, resources/, or docs/
  • kairo.toml or workspace.toml
  • forge.lock
  • examples/ packages

​
Diagnostic codes

Forge and the Kairo toolchain emit structured diagnostics with a severity level and a prefixed code. The prefix identifies which subsystem produced the diagnostic: Diagnostic severities:

​
Build output locations

Add both build/ and .forge/ to your .gitignore. Only forge.lock belongs in source control from Forge’s working files.

​
Best practices

  • Run forge check often. It is the fastest way to get diagnostic feedback without committing to a full build. Use it in your editor integration and as a pre-commit hook.
  • Commit forge.lock. The lockfile is the single source of truth for your dependency graph. Without it, builds are not reproducible.
  • Never edit build/ or .forge/ by hand. Forge owns these directories and overwrites them freely. Use forge clean if you need a reset.
  • Increment your version before publishing. Published versions are immutable. A version bump is the only way to ship a change.
  • Use forge package to inspect before you publish. Review the artifact bundle to confirm it contains exactly what you expect.

​
Next steps

Pulse

Run your compiled Kairo application with the Pulse runtime.

Dependencies

Understand how Forge resolves and locks your dependency graph.