spec-editor Pro is in early access. Request access

Quickstart

This page takes you from nothing to a validated requirements model on your own machine. Every command here runs on the open core: no license, no account, no model provider. Where the paid part starts is said at the end.

What you need

  • Python 3.11 or newer.
  • Git.
  • A terminal. The commands below are written for macOS and Linux shells.

Install

spec-editor is installed from its GitHub repository. There are two ways: the install script, or a plain git checkout.

The install script

curl -sSL https://raw.githubusercontent.com/spec-editor/spec-editor/main/install.sh | bash -s -- --dev

What the script does, in order:

  1. Looks for Python 3.11 or newer (python3.13, python3.12, python3.11, then python3). It stops with a hint if none is found.
  2. Creates the directory ~/.spec-editor and a virtual environment in ~/.spec-editor/.venv.
  3. With --dev: clones the repository into ~/.spec-editor/src (branch main) and installs it into the virtual environment in editable mode with pip install -e.
  4. Appends one export PATH=... line for the virtual environment to your shell start-up file (~/.zshrc, ~/.bashrc or the fish config), unless a line mentioning spec-editor is already there.
  5. If ~/.local/bin exists, links spec-editor into it.

The --dev option installs the current code straight from the repository. Other options: --dir DIR to change the install directory, --python PY to name the interpreter, --branch BR to pick a branch (this implies --dev), --no-venv to install into the Python you are already using.

To read the script before you run it, download it first:

curl -sSLO https://raw.githubusercontent.com/spec-editor/spec-editor/main/install.sh
less install.sh
bash install.sh --dev

A git checkout

git clone https://github.com/spec-editor/spec-editor.git
cd spec-editor
python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Check the installation

spec-editor --version
spec-editor --help

The full command list is in the CLI reference.

Create a project

A project is a folder. Give the path with -p and the methodology with -m:

spec-editor init -p my-system -m waterfall
cd my-system

Run spec-editor init with no arguments to use the interactive mode. It asks which model provider to use, then, unless you passed -m, describes your domain and either picks the closest bundled methodology or, on request, generates one. The provider choice matters only for the parts that call a model. Everything on this page works without one.

The bundled waterfall methodology is translated into five languages. spec-editor methodology list prints the catalog. The concepts page explains what a methodology contains.

What appears on disk

init writes a methodology.yaml (a copy of the one you chose), an empty aspects/ folder where the model will live, folders source/, sources_raw/, logs/ and tests/, a local.yaml with your settings, and a copy of the bundled skill files. With the methodology waterfall it may also propose an agents.yaml. Commit the folder to git: the model is plain files next to your code.

Create the first requirement

A requirement is an element of the model. There are two ways to create one, and both give the same result: a Markdown file under aspects/.

In the web interface

spec-editor ui

The interface opens in your browser at http://127.0.0.1:3080. Press ＋ New element, choose the aspect modules and the element type module, and type the title Order Export. The id MOD-001 is suggested for you. Save.

Press ＋ New element once more for a part of that module: element type component, title CSV Writer, parent MOD-001.

The VS Code extension has the same form under the command “Spec Editor: Create Element”; see editors.

From the command line

spec-editor element add --type module --title "Order Export" \
  --check "pytest tests/test_export.py -q"

spec-editor element add --type component --parent MOD-001 --title "CSV Writer" \
  --check "pytest tests/test_csv_writer.py -q"

Each command prints the id it gave the element and the path of the file it wrote. --check adds an acceptance criterion: a command that must exit with code 0.

The result

The folder tree is the tree of the system. A component that belongs to a module lies in a folder named after that module:

my-system/
├── methodology.yaml
└── aspects/
    └── modules/
        ├── MOD-001.md
        └── MOD-001/
            └── COM-001.md

Requirements element explained

You do not have to write this file yourself, but it is plain text and worth reading once. It starts with machine-readable fields between two --- lines, then comes the text for a human. This is aspects/modules/MOD-001.md:

---
id: MOD-001
aspect: modules
element_type: module
title: Order Export
status: draft
acceptance:
  - id: AC-1
    kind: deterministic
    command: pytest tests/test_export.py -q
    expected: exits with code 0
---

# Order Export

Exports the orders of one calendar month as a CSV file,
one row per order. The code lives in `src/export/orders.py`.
Field Meaning
id Unique id. The prefix is a convention of the methodology (MOD for a module); the number is suggested for you.
aspect The part of the model the element belongs to. Here: modules.
element_type A type declared by that aspect. Here: module.
title A short name.
status draft, reviewed, confirmed, blocked or deprecated. A new element is a draft.
acceptance The checks that decide whether the requirement is met. See concepts.
parent The id of the element this one belongs to. A top-level element has none.

Validate

spec-editor validate

validate reads every element and checks the model against the methodology: readable files, unique ids, required fields, parents that exist, relationship types and element types the methodology declares, and the form of each requirement (for example a requirement without acceptance criteria). It exits with code 0 when nothing is an error.

Warnings do not fail the run. On the two elements above you can expect warnings about operations that the elements do not declare yet; they are advice about the form of a requirement. --strict turns warnings into errors, which suits a CI job. --json prints the result as JSON. The option --scope links checks the @implements links between model and code; see concepts.

See the model

spec-editor status

Prints a table of the elements with aspect, type, status and parent. Add -m for connectivity metrics, -a modules for one aspect, --json for machine output.

spec-editor view -e MOD-001
spec-editor view -o model.html

The first form prints one element in the terminal. The second renders the whole model as a Mermaid graph in an HTML file; without -o the page opens in your browser. -a modules limits the graph to one aspect, -d MOD-001 focuses it on an element and its neighbours.

Export

spec-editor export -f srs -o srs.md
spec-editor export -f html -o model.html
spec-editor export -f trlc -o requirements.trlc

srs is a software requirements specification in the style of IEEE 830, as Markdown. html is a styled page with the relationships. trlc is requirements-as-code. Three more formats exist (openapi, jira, compliance) but they need element types that the bundled methodology does not have; use them with a custom methodology.

Connect an external agent through MCP

spec-editor runs an MCP server (Model Context Protocol) so that a coding agent can ask for the requirements it needs instead of reading a whole document. The agent starts the server itself: you give the client a command, and the client runs it.

For a client that reads an .mcp.json file, add this to the file in the root of your workspace, with the path of your project:

{
  "mcpServers": {
    "spec-editor": {
      "command": "spec-editor",
      "args": ["mcp", "-p", "/path/to/my-system"]
    }
  }
}

For Claude Code you can register the same command from a terminal:

claude mcp add spec-editor -- spec-editor mcp -p /path/to/my-system

Cursor, Zed and other clients take the same command and args in their own settings. The default transport is stdio. spec-editor mcp --transport http --port 8001 serves HTTP on 127.0.0.1 and --read-only registers only the read-only tools on that transport. The tools are listed in the MCP reference.

What the open core does alone

On its own the open core gives you the model and the tools around it: the element files and their folder tree, the methodology, validation, links between code and requirements, the local web interface, export, the MCP server and the editor integrations. You write and review the requirements yourself, or an external agent does it through MCP.

Where Pro starts

The delivery team starts with spec-editor Pro: analysts that turn sources into elements, a project manager, a coder, a tester and devops, review stages, test stands and cost control. Pro is in early access; see pricing to ask for it. Nothing on this page needs it.

Next