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

In Forge `v0.3.0` and later, add `--agent-ready` to generate `FORGE_SPEC.md` and
`AGENTS.md` alongside the normal working template. It is deterministic
scaffolding only: Forge does not contact or launch an AI agent.

The unreleased interactive `--agent` mode discovers the configured Omarchy
agent, gathers and confirms a complete specification, creates a local Git
baseline and `AGENT_PROMPT.md`, then launches the agent only after the user
confirms the displayed plan and unattended-permission warning. It cannot be
combined with `--non-interactive`, `--dry-run`, `--force`, or `--agent-ready`.
It never executes QML, installs a plugin, configures a Git remote, or pushes.
Forge asks whether to use reference files or the detailed questionnaire.
Reference mode accepts up to ten local text, Markdown, PNG, JPEG, WebP, or SVG files
through a generated `references/` drop directory and makes them the primary
product brief. The agent must inventory every visible or described function,
control, value, state, action, and configuration hook. Forge separately confirms
local-command, network, and persistence boundaries. Questionnaire mode retains
the exact bar, dashboard, action, data-source, and command questions.

## `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)