> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Forge CLI Command Reference

> Complete reference for all Forge CLI commands: restore, check, build, test, package, publish, and clean with flags and diagnostic codes.

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 — if the current directory is not a package root or workspace root, Forge will fail with an explicit error. This page is the complete reference for all Forge commands, their outputs, and the diagnostic code system.

<Note>
  Forge does not search parent directories for a manifest in v0.1. You must run Forge commands from a directory that directly contains `kairo.toml` (package root) or `workspace.toml` (workspace root).
</Note>

## `forge restore`

Resolves all dependencies declared in your project manifest and writes a `forge.lock` file that pins exact versions for reproducible builds. Run `forge restore` before your first build in any environment where the lock file may be absent or out of date.

```bash theme={null}
forge restore
```

**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.

<Note>
  Commit `forge.lock` to source control for applications. Libraries can optionally omit it, but pinning is recommended for reproducibility.
</Note>

## `forge check`

Validates your source code and reports diagnostics without producing any build artifacts. Use this for fast feedback during development.

```bash theme={null}
forge check
```

**What it does:**

* Restores dependencies if needed.
* Parses and type-checks all `.ak` source files.
* Emits diagnostics (errors, warnings, and notes) 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/`.

<Tip>
  Run `forge check` in your editor's save hook or CI pipeline for fast feedback. It is significantly faster than `forge build` because it stops after diagnostics and does not proceed into artifact generation.
</Tip>

## `forge build`

Runs the full compilation pipeline: parsing, type-checking, and artifact generation. Use this when you need deployable output.

```bash theme={null}
forge build
```

**What it does:**

* Performs everything `forge check` does.
* Generates compiled artifacts into `build/`.
* Writes Forge-internal metadata to `.forge/`.

**Outputs:**

* `build/` — compiled application artifacts.
* `.forge/` — Forge-internal metadata consumed by the Pulse runtime.

<Note>
  `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.
</Note>

## `forge test`

Discovers and runs the project's test suite.

```bash theme={null}
forge test
```

**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.

```bash theme={null}
forge package
```

**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.

```bash theme={null}
forge publish
```

**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.

<Warning>
  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`.
</Warning>

## `forge clean`

Removes all generated build output and Forge-internal metadata. Source files, manifests, and the lock file are never touched.

```bash theme={null}
forge clean
```

**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.

<Note>
  `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.
</Note>

## 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.

| Prefix | Origin                    | Description                                                                                    |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------------- |
| `FRG`  | Forge (general)           | Project-level errors: missing manifests, invalid configuration, dependency resolution failures |
| `SYN`  | Syntax                    | Parse-level errors in `.ak` source files                                                       |
| `BCK`  | Backend / code generation | Errors during compilation artifact generation                                                  |
| `PLS`  | Pulse runtime             | Runtime validation and execution errors                                                        |

Diagnostics are emitted at one of three severities:

| Severity  | Meaning                                                   |
| --------- | --------------------------------------------------------- |
| `error`   | Blocks successful completion of the current command stage |
| `warning` | Reported but does not block completion by default         |
| `note`    | Supporting context attached to an error or warning        |

**Example diagnostics:**

```
SYN0042  Expected ':' after parameter name
FRG0011  Dependency 'Astra.Data' not found in registry
BCK0007  Artifact generation failed for target
PLS0031  Entrypoint metadata missing in application manifest
```

## Build Output Layout

After a successful `forge build`, your project directory contains the following generated structure:

```
your-project/
├── kairo.toml          # project manifest (source, not generated)
├── forge.lock          # pinned dependencies (source, not generated)
├── src/                # your .ak source files (source, not generated)
├── build/              # compiled artifacts (generated by forge build)
│   └── ...
└── .forge/             # Forge internal metadata (generated by forge build)
    ├── build-plan.json
    └── output-manifest.json
```

<Tip>
  Add `build/` and `.forge/` to your `.gitignore`. Both directories are fully reproducible from source via `forge restore && forge build`.
</Tip>