# The solforge command-line

This chapter enumerates every command and every option. Where a flag has a non-obvious semantic, it is explained inline; where a flag's behaviour depends on configuration, the relevant key in [Configuration files](/solanatestforge-docs/part-ii-reference/configuration.md) is cited.

## Global flags

Global flags are accepted before any subcommand.

| flag           | argument | meaning                                                                         |
| -------------- | -------- | ------------------------------------------------------------------------------- |
| `--version`    | —        | print the binary version and exit                                               |
| `-h`, `--help` | —        | print the help text for the current scope                                       |
| `--config`     | path     | use the configuration file at the given path instead of the auto-discovered one |

## `solforge init`

```
solforge init
```

Scaffolds a new test project in the current directory. Creates a `.solforge.toml` with sensible defaults, an empty `tests/` directory, and a `.gitignore` entry for `.solforge/snapshots/`. The command is currently a stub and will be expanded in a future release; see the changelog of the source repository for status.

## `solforge fork <network> <programId>`

```
solforge fork devnet 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
solforge fork mainnet <id> --slot 240118022
```

Materialises a snapshot of on-chain state.

| flag           | argument | meaning                                           |
| -------------- | -------- | ------------------------------------------------- |
| `-s`, `--slot` | integer  | fork at a specific slot rather than the chain tip |

Snapshots land under `.solforge/snapshots/<network>/<programId>/<slot>.json`. Re-running with the same `(network, programId, slot)` is a no-op. When `--slot` is omitted, the engine resolves the current confirmed slot at call time; the resolved value is recorded in the snapshot's filename so that subsequent runs can be reproduced.

## `solforge test`

```
solforge test
solforge test -f tests/withdrawal.spec.ts
```

Runs the project's test suite against the most recent fork.

| flag           | argument | meaning                                  |
| -------------- | -------- | ---------------------------------------- |
| `-f`, `--file` | path     | run only the test file at the given path |

If no fork has been taken, the framework will refuse to run; the diagnostic explicitly recommends the appropriate `solforge fork` command. This is intentional. A test command that silently auto-forks against the chain tip would obscure what is being tested.

## `solforge security <programId>`

```
solforge security 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
```

Runs the static security catalogue against the IDL of the named program. The full lifecycle of a single check is described in [The lifecycle of a check](/solanatestforge-docs/part-i-foundations/lifecycle-of-a-check.md). The list of built-in rules and their semantics lives in [Security checks](/solanatestforge-docs/part-ii-reference/security-checks.md).

The exit code is `0` if no finding meets or exceeds the configured failure threshold, `1` otherwise. Threshold and rule selection are configurable; see [Configuration files](/solanatestforge-docs/part-ii-reference/configuration.md).

## `solforge fuzz <programId>`

```
solforge fuzz <programId>
solforge fuzz <programId> -n 5000
```

Drives the fuzz engine against every instruction handler in the program's IDL.

| flag                 | argument | meaning                                                  |
| -------------------- | -------- | -------------------------------------------------------- |
| `-n`, `--iterations` | integer  | number of input vectors per instruction (default `1000`) |

The fuzz engine's coverage and limitations are described in [The fuzz engine](/solanatestforge-docs/part-ii-reference/fuzz-engine.md). Reproducible runs require pinning a seed; the recipe [Reproducing mainnet bugs locally](/solanatestforge-docs/part-iii-recipes/reproducing-mainnet-bugs.md) demonstrates the convention.

## Exit codes

| code | meaning                                                                                                    |
| ---- | ---------------------------------------------------------------------------------------------------------- |
| `0`  | command completed within configured thresholds                                                             |
| `1`  | command-specific failure (fork RPC error, IDL not found, finding above threshold, fuzz invariant breached) |
| `2`  | usage error (unknown command, missing required argument)                                                   |

A non-zero exit always corresponds to a single line of human-readable diagnostic on stderr. JSON-shaped output, when requested, never appears on stderr; that channel is reserved for diagnostics.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://solanatestforge.gitbook.io/solanatestforge-docs/part-ii-reference/cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.