Install, configure, and master the fp CLI
Everything you need to track feature parity, in one place. Install the CLI, point it at your environment, then learn the core concepts and full command reference — no jumping between pages.
Install the fp CLI
Pick one of these options — they both install the same CLI. Requires Ruby 3.0+.
Already have fp? Run fp update to get the latest version. See update instructions.
Requirements
Ruby 3.0+
macOS: brew install ruby
Ubuntu: sudo apt install ruby-full
Network access
The CLI calls the FeatureParity API (defaults to api.featureparity.dev).
API key
Generate one under Account → Agents & API keys. Starts with fp_.
Update the CLI
fp doctor shows the newest version, and fp tells you, at most once a day, when the one you have is behind.
fp updateThe changelog lists what changed in every release.
That command arrived in fp 0.0.34. If yours answers Unknown command: update, it is 0.0.33 or older: update the gem directly, or run the installer script again. Both do the same thing.
gem update featureparityThen refresh what fp wrote into each repo that uses it:
fp skill install
fp init --forceThe first replaces the agent skill, if the repo has it. The second rewrites the FeatureParity section of AGENTS.md.
For AI agents
Teach your coding agent to use fp with the Agent Skills package — one install works across Claude Code, Codex, Cursor, Gemini CLI, Kiro, Copilot, and more.
fp skill installThe skill ships inside the fp gem. This copies it into the repo's .claude/skills (Claude Code) and .agents/skills (Codex, Cursor, Gemini CLI and others), or your home directory with --global, so your agent knows how to add fp:<slug> markers, report evidence (including from JUnit reports), and propose requirements — no hand-holding required. Re-run it after upgrading the gem.
Working in one repository? fp init --project <slug> writes the skill's core guidance into the repo's AGENTS.md (or its CLAUDE.md, if that's what the repo has), so an agent that reads it needs no skill install.
Installed? Next,
Configure & verify
Give the CLI your key. It already talks to FeatureParity, so the key is all it needs.
Add your API key
Mint a key under Account → Agents & API keys → Mint Key. Keys start with fp_ and are shown once. For interactive use, run setup and paste the token when prompted:
fp setupOr, for CI and automation, export the key as environment variables:
# add to your shell profile or CI env
export FP_API_KEY=fp_your_key_hereConfirm the resolved configuration
This prints the profile, environment, API URL, and (masked) key fp will actually use:
fp whoamiVerify the connection
List your projects to confirm the CLI is talking to the right server:
fp projectsYour CLI is connected. Next, mark tests with the fp:<slug> marker and report evidence with fp report.
Core concepts
Four ideas underpin everything in FeatureParity. Learn these and the rest follows.
Requirements
A requirement describes something your product must do, identified by a stable slug. Requirements are defined once and tracked everywhere.
Surfaces
A surface is a platform your product runs on — web, iOS, Android, API, ops tooling. Each requirement is tracked independently per surface.
Evidence
Evidence binds a test to a requirement via the fp:<slug> marker. Report a single test, or upload a whole JUnit report at once. Agents report present or stub; CI reports passing or failing.
Parity Matrix
The matrix cross-references requirements against surfaces so gaps light up instantly. Green means confidence; blank means action.
Quickstart
From zero to your first reported evidence in five steps.
Install the CLI
The fp CLI is how you and your agents talk to FeatureParity. Requires Ruby 3.0+.
gem install featureparityConfigure a profile
Mint an API key under Account → Agents & API keys, then run setup to validate and save it.
fp setupList your requirements
Confirm the CLI is connected and see what your project needs to satisfy.
fp list --project acmeMark a test
Add a one-line fp:<slug> marker above any test to bind it to a requirement. Pin surfaces inline with @ — e.g. fp:print_container_qr@api,web — when one test covers several.
# fp:print_container_qrReport evidence
Tell FeatureParity the test exists. Report one test, or upload a JUnit report with --junit to cover every marked test at once — no CI required. The matrix updates as evidence lands.
fp report print_container_qr --project acme --surface webCLI reference
The fp CLI works in local dev, CI pipelines, and agent workflows. Every command supports --json for machine-readable output.
fp projectsList the projects you can access.fp projects create <slug> --name "..."Create a project from the CLI. It belongs to whoever minted your key.fp list --project XList active requirements for a project.fp list --project X --gapsShow only requirements with no evidence yet.fp show <slug> --project XInspect a requirement and its receipts.fp report <slug> ...Report evidence for a requirement on a surface.fp report --junit <file> ...Upload evidence for every marked test in a JUnit report — no CI needed.fp propose --project X --slug YPropose a new requirement as a draft.fp propose-change <slug> --project XPropose a change to an existing requirement (or --removal to propose deleting it).fp history <slug> --project XSee what changed, what prompted it, and how the test evidence moved.fp matrix --project XRender the parity matrix as ASCII (or --csv).fp surfaces add <new> --project X --from <existing>Add a platform: create the surface and propose it on every requirement the existing one carries. Nothing is required until a person approves it.fp surfaces batch-draft <surface> --project X --slugs a,bPropose a surface on a chosen list of requirements in one step.fp config set api_url <url>Point the CLI at a non-default API (e.g. a dev/ephemeral environment).fp whoamiShow the resolved profile, environment, API URL, and (masked) key.fp repos set <surface> <path>Map a surface to a local repo on this machine.Run fp help at any time for the full usage reference.
Guides
Deeper walkthroughs for common tasks.
The parity matrix
See how requirements and surfaces come together in a live parity view.
Open the matrixReady to start?
Install the CLI, mint an API key, and watch your parity matrix fill up.