CLI

The dot•requirements CLI (dotreq) manages your requirements workflow: initialize projects, sync with the cloud, validate files, and configure AI integrations.

Installation

npm install @popoverai/dotrequirements

pnpm add @popoverai/dotrequirements

yarn add @popoverai/dotrequirements

For MCP server usage with AI assistants, a global install is often more convenient:

npm install -g @popoverai/dotrequirements

Note: Examples use dotreq for brevity, and because we’re pretty sure that’s what you’re going to end up using too. The full command dotrequirements also works.

Commands

dotreq init

Initialize a project in the current directory. You’ll be prompted to choose between:

• Create a new project — Creates a new cloud project (or local-only if not authenticated)
• Connect to an existing project — Links to a project that already exists in the cloud

dotreq init
dotreq init --name my-project
dotreq init --invite abc123xyz

Init will:

• Create .requirements/ directory with example requirements
• Save project credentials to .requirements/project-settings.json (if authenticated)
• Update .gitignore to protect credentials
• Pull existing requirements (if connecting to an existing project)

Options:

Joining a team via invite:

If a team admin shares an invite command with you, you can join the team and connect to a project in one step:

npx dotrequirements init --invite abc123xyz

This will:

1. Show you the team name before authentication
2. Open a browser for sign-in (or sign-up if you’re new)
3. Add you to the team automatically
4. Prompt you to select a project to connect
5. Pull the project’s requirements

dotreq link

Connect to an existing cloud project. Opens a browser for authentication, then prompts you to select your team and project.

dotreq link

Use link when:

• You’ve already run init locally and want to connect to the cloud
• You’re on a new machine or clone and need to connect to an existing project
• Your credentials have expired and need refreshing

dotreq pull

Sync requirements from dot•requirements cloud to local files.

dotreq pull
dotreq pull --project <project-id>
dotreq pull --document <document-id>
dotreq pull --share <token>

Options:

First-time setup with a share token:

If a team member shares a pull command with you, you can pull requirements without creating an account:

npx @popoverai/dotrequirements pull --share drt_abc123...

This gives you read-only access to view requirements. To push changes or report coverage, run dotreq link afterward to set up full access.

Where files are written:

Pull always writes to the .requirements/ directory. Files are matched by document ID (stored in frontmatter), so renaming a file won’t cause duplicates. New documents are named by sanitized title (e.g., “Login Flow” → login-flow.requirements.md).

Note: If you’ve moved a requirements file outside .requirements/ (e.g., colocated with a component), pulling will create a new copy in .requirements/. The test harness will find both files, but only the one in .requirements/ is managed by pull.

dotreq push

Push local requirements changes to dot•requirements cloud.

dotreq push
dotreq push .requirements/auth.requirements.md
dotreq push --yes

Without --yes, shows a diff preview and prompts for confirmation before pushing.

Options:

Which files are pushed:

• dotreq push (no arguments) — Pushes all *.requirements.md files in .requirements/
• dotreq push <path> — Pushes the specified file from any location

If you colocate requirements files with components, you’ll need to push them explicitly by path.

dotreq validate

Validate requirements files against the schema. This checks file structure and format—it does not run your test suite.

dotreq validate
dotreq validate --file .requirements/auth.requirements.md

Options:

dotreq search

Search requirements by text or regex across every .requirements.md file in the project. Searches requirement IDs, content, and labels.

dotreq search "login"
dotreq search "AUTH-.*" --regex

Options:

dotreq get

Print a requirement (or subtree) by ID, with its test references and source code locations.

dotreq get AUTH-LOGIN-1
dotreq get AUTH-LOGIN-1.0

Both numeric paths (AUTH-LOGIN-1.0.1) and label paths (AUTH-LOGIN-1.given.and) resolve to the same node.

dotreq list

Summarize requirements in the project. Without flags, lists every root requirement with its child count. With --untested, filters to roots that have no requirement() references anywhere in the codebase.

dotreq list
dotreq list --untested

Options:

dotreq requirements-for

Show which requirements a test file references, with the line where each requirement() call lives.

dotreq requirements-for src/auth.test.ts

Useful when you’ve inherited tests and want to see what requirements they claim to cover.

dotreq tests-for

Show which tests reference each requirement in a .requirements.md file. The inverse of requirements-for.

dotreq tests-for .requirements/auth.requirements.md

Useful for spotting requirements that have drifted out of test coverage.

dotreq acceptance-test

Run browser-based acceptance tests against requirements. Uses AI-powered browser automation to verify that your application behaves as specified.

dotreq acceptance-test LOGIN-1
dotreq acceptance-test LOGIN-1 https://example.com
dotreq acceptance-test LOGIN-1 --json

Given a requirement like:

LOGIN-1: User can log in with valid credentials
  0. given → user is on login page
  1. when → user enters valid email and password
  2. then → user sees dashboard

Running dotreq acceptance-test LOGIN-1 produces:

Testing LOGIN-1 against https://your-app.com...

✓ LOGIN-1: User can log in with valid credentials
  ✓ LOGIN-1.0 (given): user is on login page
  ✓ LOGIN-1.1 (when): user enters valid email and password
  ✓ LOGIN-1.2 (then): user sees dashboard

4/4 passed

Options:

Configuration required:

Browser testing needs a Stagehand model and the API key for that model’s provider in project-settings.json:

{
  "projectId": "your-project-id",
  "projectSecret": "your-project-secret",
  "defaultURL": "https://your-app.com",
  "browserTest": {
    "modelName": "gateway/anthropic/claude-haiku-4-5",
    "modelApiKey": "your-api-key"
  }
}

See Browser Test Configuration for all available settings.

dotreq cts (Alpha)

Generate behavioral requirements from an existing codebase. Packs the codebase, plans a behavioral outline, fans out per-area specifier agents, runs a dual review loop, and writes .requirements/*.requirements.md files.

dotreq cts run --scope src

This is alpha-quality and prompt-sensitive — output quality varies by codebase and we’re actively iterating. See Codebase to Spec for full documentation, prerequisites, and exit codes.

dotreq ai-setup

Configure the MCP server for AI assistants. Interactive setup that configures your chosen assistant and adds workflow guidance to your project’s context file.

dotreq ai-setup

Supports: Claude Code, Claude Desktop, Cursor, Google Antigravity, OpenAI Codex, GitHub Copilot.

See Local MCP for details.

dotreq mcp

Start the MCP server manually. (Typically not needed—AI assistants start it automatically after ai-setup.)

dotreq mcp

dotreq harness prepare

Parse requirements and build a lookup cache for multi-language test tracking. Run before tests in non-JavaScript projects.

dotreq harness prepare
dotreq harness prepare --quiet

Creates .requirements/.cache/lookup.json (requirement lookup) and .requirements/.cache/tracking.jsonl (empty tracking file). JavaScript projects don’t need this — the test harness calls prepare() automatically.

Options:

dotreq harness finalize

Aggregate test tracking data and print a coverage report. Run after tests in non-JavaScript projects.

dotreq harness finalize
dotreq harness finalize --push
dotreq harness finalize --quiet
dotreq harness finalize --push --context pytest

Options:

dotreq report

View coverage from the most recent local test run, or from the cloud-persisted record.

dotreq report                                       # local cache (default)
dotreq report --source cloud                        # cloud-persisted record
dotreq report --source cloud --branch main          # filter to a branch
dotreq report --source cloud --since 1700000000000  # filter to records after a timestamp
dotreq report --requirement AUTH-LOGIN              # scope to one requirement
dotreq report --format json

Options:

Local source (the default) reads from .requirements/.cache/tracking.jsonl populated by your most recent test run on this machine. Warns if requirements have changed since the last harness prepare, or if no tracking data exists.

Cloud source reads the persisted record from dot•requirements cloud. Covers every root requirement — both those with cloud coverage records and those that have never been tested. Requires cloud authentication (run dotreq link first).

--branch and --since only apply with --source cloud; using them with the local source errors out.

dotreq style-check

Get AI feedback on a requirements file or a test file. Works on both *.requirements.md files (catches vagueness, missing preconditions, untestable assertions) and test files (checks semantic alignment with referenced requirements).

dotreq style-check .requirements/auth.requirements.md
dotreq style-check src/auth.test.ts
dotreq style-check .requirements/auth.requirements.md --keys AUTH-LOGIN-1,AUTH-LOGIN-2

Options:

When .requirements/STYLE.md exists in your project, its contents are included in the AI’s prompt so project-specific style preferences influence the feedback.

Cloud authentication required. Run dotreq link first.

dotreq review-test

AI-powered semantic review of a test file against its referenced requirements. Validates that test setup matches GIVEN conditions, actions match WHEN triggers, and assertions match THEN outcomes.

dotreq review-test src/auth.test.ts

Catches tests that reference a requirement but don’t actually validate what the requirement specifies — especially valuable when AI assistants write tests.

Cloud authentication required.

dotreq create-requirement-document

Print a Markdown template demonstrating the requirements file format, with format guidance and style examples. Use it to seed a new .requirements.md file or to prime an AI assistant’s context before authoring.

dotreq create-requirement-document
dotreq create-requirement-document .requirements/auth.requirements.md

When a file path is provided, the template references that filename. If .requirements/STYLE.md exists, its contents replace the bundled default style body in the output. The template is printed to stdout — redirect it into a new file or pipe it into your editor.

Configuration

The CLI stores project credentials in .requirements/project-settings.json:

{
  "projectId": "your-project-id",
  "projectSecret": "your-project-secret"
}

This file is automatically added to .gitignore during initialization.

Environment Variables

Browser Test Configuration

For dotreq acceptance-test, add these settings to project-settings.json:

{
  "defaultURL": "https://your-app.com",
  "browserTest": {
    "modelName": "gateway/anthropic/claude-haiku-4-5",
    "modelApiKey": "your-api-key",
    "vercelBypassSecret": "optional-vercel-secret",
    "browserbaseApiKey": "optional-browserbase-key",
    "browserbaseProjectId": "optional-browserbase-project"
  }
}

Pick any Stagehand-supported model. Example values: gateway/anthropic/claude-haiku-4-5 (Vercel AI Gateway key), google/gemini-3-flash-preview (Gemini key).

Setting both browserbaseApiKey and browserbaseProjectId switches runs from LOCAL (spawns Playwright on your machine) to BROWSERBASE (managed cloud browsers).

File Discovery

The CLI finds **/*.requirements.md files anywhere in your project, not just in .requirements/. This enables colocation with components or tests.

Ignored directories: node_modules/, dist/, .git/, build/, example/, examples/

Project Root Detection

The CLI determines project root in this order:

1. Explicit DOTREQUIREMENTS_PROJECT_ROOT environment variable
2. Walking up from current directory looking for .requirements/
3. Current working directory

Monorepo Considerations

We recommend initializing at the monorepo root. Dot•requirements projects are designed to be analogous to codebases. In this configuration, all packages share the same project and credentials.

Supported configurations:

• Single root at monorepo level
• Peer directories with separate projects (independent projects)

Unsupported configurations:

• Nested roots (a directory containing .requirements/ with another .requirements/ in a child directory)
• Same project accessed from different directories without shared root

What Works Offline

These features work without cloud authentication:

• Write requirements (.requirements.md files)
• Validate requirements (dotreq validate)
• Search and explore (dotreq search, get, list, requirements-for, tests-for)
• Reference requirements in tests (requirement())
• Local coverage reporting (dotreq report, default --source local)
• Generate a requirements template (dotreq create-requirement-document)
• MCP tools that mirror the offline CLI verbs

These features require cloud authentication:

• Sync requirements (pull / push)
• Cloud coverage queries (dotreq report --source cloud)
• AI-powered style checking and test review (dotreq style-check, dotreq review-test)
• Team collaboration