---
title: Quickstart
description: Install Forge in Omarchy, create a plugin, check it, preview it safely, and try it in the shell.
---

# Quickstart



This guide takes you from an Omarchy terminal to a running example plugin.
Forge runs on the Linux machine where Omarchy is installed. If your everyday
computer is Windows or macOS, enter the terminal **inside Omarchy** before
continuing.

## Prerequisites [#prerequisites]

* Omarchy 4 with shell plugin support.
* A terminal open inside Omarchy.
* Git and `curl`, used for installation and local plugin development.

You do not need Go or `sudo` to use the published Forge release.

## Install Forge [#install-forge]

Copy this entire block into the Omarchy terminal. It detects whether the machine
uses an AMD/Intel or ARM processor, downloads only the matching Forge `v0.2.0`
archive, verifies its checksum, and installs it for your user:

```bash
set -eu
version="0.2.0"
case "$(uname -m)" in
  x86_64) arch="amd64" ;;
  aarch64|arm64) arch="arm64" ;;
  *) echo "Unsupported CPU: $(uname -m)" >&2; exit 1 ;;
esac
workdir="$(mktemp -d)"
cd "$workdir"
curl -fLO "https://github.com/omarchy-forge/forge/releases/download/v${version}/omaforge_${version}_linux_${arch}.tar.gz"
curl -fLO "https://github.com/omarchy-forge/forge/releases/download/v${version}/checksums.txt"
sha256sum --ignore-missing --check checksums.txt
tar -xzf "omaforge_${version}_linux_${arch}.tar.gz"
install -Dm755 omaforge "$HOME/.local/bin/omaforge"
"$HOME/.local/bin/omaforge" version
```

This changes only `~/.local/bin/omaforge`. If a new terminal says that
`omaforge` is not found, run it as `$HOME/.local/bin/omaforge` or add
`~/.local/bin` to your `PATH`.

## Create a bar widget [#create-a-bar-widget]

```bash
cd "$HOME"
omaforge init project-pulse --git
```

Forge asks for the remaining information. Use a unique reverse-domain plugin ID
such as `dev.yourname.project-pulse`. You can press Enter to accept appropriate
defaults.

Forge refuses dangerous targets, symlinked output trees, and unexpected files.
Use `--dry-run` to preview the complete write plan without creating anything.

## Check and validate [#check-and-validate]

```bash
cd "$HOME/project-pulse"
omaforge check .
omaforge doctor .
omarchy plugin validate .
```

`check` inspects project structure without executing plugin QML. `doctor`
performs read-only local environment probes. The final command runs Omarchy's
official validator; Forge complements it rather than replacing it.

## Preview safely [#preview-safely]

Review the generated QML and local commands before acknowledging that you trust
the code. Then run it in Forge's isolated temporary runtime:

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

Try empty and error states, or keep the preview refreshed while editing:

```bash
omaforge dev . --trust-plugin-code --state empty
omaforge dev . --trust-plugin-code --state error
omaforge dev . --trust-plugin-code --state ready --watch
```

Stop watch mode with `Ctrl-C`. These commands do not install the plugin, change
Omarchy configuration, or connect to the live shell.

## Try the plugin [#try-the-plugin]

Review the generated source before enabling it; plugins run unsandboxed inside
the long-lived Omarchy Shell process.

```bash
omarchy plugin add "$PWD" --enable
./demo/run empty
```

When testing is complete, remove it. Replace the example ID with the exact value
entered during creation:

```bash
omarchy plugin remove dev.yourname.project-pulse
```

## Capture a preview [#capture-a-preview]

Forge can capture only the plugin-declared panel content—never the desktop:

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

Forge refuses to overwrite an existing image.

## What to do next [#what-to-do-next]

* Read the [command reference](/docs/commands) for every flag and output format.
* Learn the generated structure in [plugin anatomy](/docs/plugin-anatomy).
* Add automated checks using the generated GitHub Actions workflow.
* Edit the QML, rerun `omaforge check .`, and preview each state before enabling
  the plugin again.

## Build Forge from source [#build-forge-from-source]

This path is only for contributors working on Forge itself. It requires Go 1.23
or newer:

```bash
git clone https://github.com/omarchy-forge/forge.git
cd forge
go build -o ./tmp/omaforge ./cmd/omaforge
./tmp/omaforge version
```


---

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

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