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

Init will:

• Create or update .env.local with project credentials
• Create .requirements/ directory with example requirements
• Update .gitignore to protect credentials
• Pull existing requirements (if connecting to an existing project)

Options:

dotreq link

Connect to an existing project. This is the same as choosing “Connect to an existing project” in init, but skips the choice prompt.

dotreq link

Use link when you’ve already run init on another machine or clone and need to connect this environment to the same project.

Requires authentication. You’ll be prompted to select your team and project.

dotreq login

Authenticate with dot•requirements cloud. Opens a browser for authentication.

dotreq login

Credentials are stored in ~/.dotrequirements/tokens.json with restricted file permissions.

dotreq logout

Clear stored authentication credentials.

dotreq logout

dotreq pull

Sync requirements from dot•requirements cloud to local files.

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

Options:

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 mcp-setup

Configure the MCP server for AI assistants. Interactive setup that configures your chosen assistant and optionally installs workflow skills.

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 .env.local:

DOTREQUIREMENTS_PROJECT_ID=your-project-id
DOTREQUIREMENTS_PROJECT_SECRET=your-project-secret

This file is automatically added to .gitignore during initialization.

Environment Variables

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