Documentation

Getting Started

Upgrading from Felix 2? Felix 3 is a breaking change and does not import V2 configuration or requirements. Preview with felix v3 migrate; apply with felix v3 migrate --harness <provider> --apply. V2.2.0 is the final V2 release. Felix Cloud users will need V3 at the announced Cloud cutover. See the V3 preview notes or download V2.2.0.

Five steps to configure Felix 3 and run your first spec. Felix 3 is a breaking-change successor; read the migration note below if you are upgrading from Felix 2.

Step 1

Install Felix CLI

Download the latest build for your OS from the Downloads page, then verify installation.

felix --version

Step 2

Register or connect your project

In your repo root, configure Felix 3 with a harness you have installed and authenticated. This creates a separate .felix3 configuration; it does not convert Felix 2 requirements or agent settings.

felix v3 setup --harness opencode

Step 3

Get your cloud API key

For Cloud work, set work_source.provider to felix-cloud in .felix3/config.json, then configure the project agent UUID. Set the project API key as FELIX_SYNC_KEY in your environment; never store it in the config file.

# .felix3/config.json: work_source.provider = "felix-cloud"
# Set work_source.cloud.agent_id to your Cloud agent UUID
$env:FELIX_SYNC_KEY = "fsk_your_project_api_key"

Step 4

Run your first spec

Create a Markdown spec with YAML frontmatter containing an ID, title, and status. Add clear acceptance criteria and configure validation commands in .felix3/config.json.

felix v3 run S-0001 --spec specs/S-0001.md

Step 5

Get cracking

Run a named spec, or mark specs ready-for-agent and let Felix select the next item. Felix 3 runs plan, build, validation, and review.

felix v3 run S-0001 --spec specs/S-0001.md
felix v3 next
felix v3 loop --max-iterations 5

Last updated: 2026-11-01