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 test

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

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

Options:

dotreq browsertest

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

dotreq browsertest LOGIN-1
dotreq browsertest LOGIN-1 https://example.com
dotreq browsertest 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 browsertest 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 requires credentials in project-settings.json:

{
  "projectId": "your-project-id",
  "projectSecret": "your-project-secret",
  "defaultURL": "https://your-app.com",
  "browserTest": {
    "geminiApiKey": "your-gemini-api-key"
  }
}

See Browser Test Configuration for all available settings.

dotreq mcp-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 mcp-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 mcp-setup.)

dotreq mcp

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 browsertest, add these settings to project-settings.json:

{
  "defaultURL": "https://your-app.com",
  "browserTest": {
    "geminiApiKey": "your-gemini-api-key",
    "vercelBypassSecret": "optional-vercel-secret",
    "browserbaseApiKey": "optional-browserbase-key",
    "browserbaseProjectId": "optional-browserbase-project"
  }
}

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 test)
• Reference requirements in tests (requirement())
• Local coverage reporting
• MCP tools for search and validation

These features require cloud authentication:

• Sync requirements (pull / push)
• Historical coverage tracking
• AI-powered style checking and test review
• Team collaboration