Skip to content

docs(install): document Homebrew #1946

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
clay-good merged 2 commits into from
Sep 22, 2026
Merged

docs(install): document Homebrew #1946

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
84eb097
docs(install): document Homebrew
clay-good Sep 21, 2026
fe485bf
docs(install): clarify the Node prerequisite
clay-good Sep 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,22 +122,28 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har

## Quick Start

**Requires Node.js 20.19.0 or higher.**
**Requires Node.js 20.19.0 or higher.** Homebrew installs it as a dependency.

Install OpenSpec globally:

```bash
npm install -g @fission-ai/openspec@latest
```

Or install the official [Homebrew formula](https://formulae.brew.sh/formula/openspec) on macOS or Linux:

```bash
brew install openspec
```

Then navigate to your project directory and initialize:

```bash
cd your-project
openspec init
```

> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
> **Want your AI to do it?** Paste the [setup prompt](docs-lab/start/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.

Now talk to your AI:

Expand All @@ -151,7 +157,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
> [!NOTE]
> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
>
> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](docs-lab/start/installation.md).

## Docs

Expand Down Expand Up @@ -208,6 +214,12 @@ AI coding assistants are powerful but unpredictable when requirements live only
npm install -g @fission-ai/openspec@latest
```

If you installed OpenSpec with Homebrew:

```bash
brew upgrade openspec
```

**Refresh agent instructions**

Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
Expand Down
22 changes: 18 additions & 4 deletions docs-lab/start/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,19 @@

## Prerequisites

OpenSpec is a Node.js CLI. You need version 20.19.0 or newer.
OpenSpec runs on Node.js 20.19.0 or newer. Homebrew installs Node.js as a
dependency, and the Nix package includes the runtime. Check your installed version
before using another install method.

In your terminal:

```bash
node --version
```

If that prints `v20.19.0` or higher, you're set. If not, install a newer Node from [nodejs.org](https://nodejs.org) or through your version manager (nvm, fnm, asdf, volta).
If that prints `v20.19.0` or higher, you're set. If not, install a newer Node from
[nodejs.org](https://nodejs.org) or through your version manager (nvm, fnm, asdf,
volta). You can skip this check when you install with Homebrew or Nix.

The workflow itself runs inside an AI coding tool: Claude Code, Cursor, or any other tool on the [supported list](../reference/supported-tools.md).

Expand Down Expand Up @@ -53,6 +57,16 @@ In your terminal:
npm install -g @fission-ai/openspec@latest
```

### Homebrew

Homebrew installs OpenSpec and its Node.js dependency on macOS or Linux. In your terminal:

```bash
brew install openspec
```

The formula is published in [homebrew-core](https://formulae.brew.sh/formula/openspec), so you don't need to add a tap.

### Yarn

`yarn global add` is Yarn Classic (1.x) only. Modern Yarn removed global installs, so use npm, pnpm, or bun instead. A global CLI doesn't have to share your project's package manager.
Expand Down Expand Up @@ -123,7 +137,7 @@ When a newer CLI is out, [`openspec update`](../reference/cli.md#openspec-update


> [!WARNING]
> On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.
> On Homebrew, run `brew upgrade openspec`. On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.

> [!NOTE]
> A global npm install belongs to one Node installation. Switch Node versions with nvm and the `openspec` command doesn't come along, so install it again under the new version.
Expand All @@ -144,7 +158,7 @@ openspec completion uninstall
npm uninstall -g @fission-ai/openspec
```

On Deno: `deno uninstall --global openspec`. On Nix: `nix profile remove openspec`. Your shell should no longer find `openspec`.
On Homebrew: `brew uninstall openspec`. On Deno: `deno uninstall --global openspec`. On Nix: `nix profile remove openspec`. Your shell should no longer find `openspec`.

**3. Delete what's left, or keep it.**

Expand Down
Loading