---
title: Command reference
description: Current Omarchy Forge CLI commands, formats, and exit behavior.
---

# Command reference



## `omaforge init` [#omaforge-init]

Create a deterministic bar-widget project.

```bash
omaforge init <directory> [options]
```

Run `omaforge init --help` for every scaffold input and safety control.

On Forge `main`, add `--agent-ready` to generate `FORGE_SPEC.md` and `AGENTS.md`
alongside the normal working template. This option is intended for the next
release and is not present in `v0.2.0`. It is deterministic scaffolding only:
Forge does not contact or launch an AI agent.

## `omaforge check` [#omaforge-check]

Run static, noninteractive, network-free checks without executing QML.

```bash
omaforge check .
omaforge check . --format text
omaforge check . --format json
omaforge check . --format sarif
omaforge check . --omarchy-version 4
```

Reports use schema version 1. Every finding has a stable rule ID, severity,
evidence location when available, remediation, and either an `official-parity`
or `forge` source.

| Exit code | Meaning                                         |
| --------- | ----------------------------------------------- |
| `0`       | No error-severity findings; warnings may exist. |
| `1`       | Project errors or report-write failure.         |
| `2`       | Invalid command usage.                          |

## `omaforge doctor` [#omaforge-doctor]

Combine Forge checks with read-only local probes for Omarchy, Quickshell, shell
IPC, optional `qmllint`, and the official validator.

```bash
omaforge doctor .
```

## `omaforge dev` [#omaforge-dev]

After reviewing the plugin's executable QML and local commands, run its
project-owned isolated runtime harness:

```bash
omaforge dev . --trust-plugin-code
omaforge dev . --trust-plugin-code --state ready
```

The trust flag is mandatory. This first development-tooling increment is a
one-shot runtime check. `--state ready|empty|error` applies a fictional state in
memory before the harness completes. It does not install or enable the plugin,
change shell configuration or watch files.

Add `--watch` to rerun a fresh isolated harness after local project changes.
The session survives failed runs so source can be repaired and stops on Ctrl-C.

## `omaforge screenshot` [#omaforge-screenshot]

Capture a fictional state from the plugin's explicitly declared panel item:

```bash
omaforge screenshot . --trust-plugin-code --state ready --output assets/preview.png
```

The command captures no desktop pixels and refuses to overwrite an existing
PNG. Plugins without an explicit `forgeScreenshotTarget` fail closed.

## `omaforge version` [#omaforge-version]

Print version, commit, build date, and supported manifest schema information.

```bash
omaforge version
```

Local source builds honestly report `dev` and unknown provenance unless linker
flags inject release metadata.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)