User Guide

This guide covers the day-to-day Reqvire CLI workflow for validating, querying, refactoring, and serving a semantic engineering model.

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/reqvire-org/reqvire/main/scripts/install.sh | bash

Build from Source

git clone https://github.com/reqvire-org/reqvire.git
cd reqvire
cargo build --release
target/release/reqvire --version

Workspace Selection

Use the global --workspace option when running Reqvire from outside the model repository. The option applies to normal CLI commands and the MCP server.

reqvire --workspace /path/to/repository validate
reqvire --workspace /path/to/repository search --filter-type requirement
reqvire --workspace /path/to/repository mcp

Convenience no-install command form:

npx -y @reqvire-org/reqvire@latest --workspace /path/to/repository validate
npx -y @reqvire-org/reqvire@latest --workspace /path/to/repository search --filter-type requirement
npx -y @reqvire-org/reqvire@latest --workspace /path/to/repository mcp

Core Commands

reqvire validateParse and validate model structure, relations, attachments, ontology, and semantic contracts.

reqvire formatPreview canonical formatting, ordering, and relation layout.

reqvire format --fixApply formatting fixes.

reqvire lintFind model quality issues such as redundant relations and cross-boundary hierarchy problems.

reqvire lint --auditableReport remediation-ready structural findings.

reqvire searchFilter the model by type, file, name, content, relations, and governance metadata.

reqvire modelRender the ontology/capability-rooted model view with Mermaid diagrams by default.

reqvire tracesGenerate verification trace trees from verifications to owning capability roots.

reqvire coverageReport verification coverage and requirement implementation coverage.

reqvire change-impactAnalyze review impact from changed model content and relations.

JSON and Output Files

Most report commands support --json. Combine it with --output to write machine-readable output directly to a file.

reqvire validate --json --output results.json
reqvire search --json --output search-results.json
reqvire lint --json --output lint-report.json
reqvire change-impact --json --output impact.json
reqvire ontologies --output ontologies.ttl
reqvire ontologies --jsonld --output ontologies.jsonld

Working with Elements

reqvire add <file>Append a new Markdown element from inline content, stdin, or a file.

reqvire add <file> --dry-runPreview a new or overridden element without writing.

reqvire rm <element>Remove an element and validate remaining links.

reqvire mv <element> <file>Move an element to another Markdown file while preserving references.

reqvire rename <old> <new>Rename an element and update links.

reqvire merge <target> <source>Merge source element content and relations into a target.

reqvire mv-file <old> <new>Move or rename a model file while updating model references.

reqvire mv-file <old> <new> --squashMerge all elements from one file into another file.

reqvire mv-asset <old> <new>Move a referenced non-model file and update references.

reqvire rm-asset <path>Remove a referenced asset from the model.

reqvire add requirements/Auth.md --content '### Token Expiry Requirement

The system shall reject expired access tokens.

#### Metadata
  * type: requirement

#### Relations
  * specify: [API Authentication](Auth.md#api-authentication)'

reqvire add requirements/Auth.md --dry-run < new-requirement.md
reqvire add requirements/Auth.md --override < cleaned-merged-requirement.md

reqvire rm "Obsolete Requirement" --dry-run
reqvire rm "Obsolete Requirement"

reqvire mv "Token Expiry Requirement" requirements/Identity/AuthRequirements.md
reqvire rename "Token Expiry Requirement" "Access Token Expiry Requirement"
reqvire merge "Access Token Validation" "Legacy Token Validation" --dry-run

reqvire mv-file requirements/OldAuth.md requirements/Identity/Auth.md
reqvire mv-file requirements/AuthDrafts.md requirements/Identity/Auth.md --squash
reqvire mv-asset docs/auth-flow.pdf docs/identity/auth-flow.pdf
reqvire rm-asset docs/obsolete-auth-flow.pdf --dry-run

Linking and Attachments

The link and unlink commands manage both relations and attachments. Attachments use a distinct command form so cross-subgraph contract dependencies stay visible.

reqvire link "Authentication" "specifiedBy" "Authentication Requirement"
reqvire link "Authentication Requirement" "verifiedBy" "Auth Test Case"
reqvire link "System Requirement" "satisfiedBy" "src/auth/login.rs"
reqvire link "Performance Requirement" attaching "#rate-limiting-constraint"

reqvire unlink "Authentication Requirement" "Auth Test Case"
reqvire unlink "Performance Requirement" "#rate-limiting-constraint"
reqvire relink "Child Requirement" "derivedFrom" "Old Parent" "New Parent"

reqvire link "Password Login Requirement" "derivedFrom" "Authentication Requirement" --dry-run
reqvire relink "Child Requirement" "derivedFrom" "Old Parent" "New Parent" --json

Validation, Formatting, and Linting

Mutating commands validate before they write. Run validation and hygiene commands explicitly in pull requests and before publishing generated reports.

reqvire validate
reqvire validate --json --output reports/validate.json

reqvire format
reqvire format --fix
reqvire format --fix --with-full-relations

reqvire lint
reqvire lint --fixable
reqvire lint --auditable
reqvire lint --json --output reports/lint.json

Search and Collection

Search is the fastest way to inspect a large model. Collect gathers an element and related upstream or downstream context with source citations, including attachment contents.

reqvire search --filter-type requirement --short
reqvire search --filter-type capability,requirement --filter-name ".*auth.*"
reqvire search --filter-status review --filter-priority high,critical
reqvire search --filter-type test-verification --not-have-relations satisfiedBy
reqvire search --filter-risk high,critical --json --output reports/risk.json

reqvire collect "Capability Requirement"
reqvire collect "Capability Requirement" --direction DOWNSTREAM --json
reqvire collect "Capability Requirement" --direction UPSTREAM --json --output context.json

Reports and Diagrams

Reqvire report commands produce Markdown by default where that is useful for review, and JSON for automation. Mermaid diagrams are emitted by model and trace views unless a machine-readable format is requested.

reqvire model
reqvire model --mmd
reqvire model --json --output reports/model.json
reqvire model --from "API Authentication"
reqvire model --filter-type capability,requirement

reqvire traces
reqvire traces --json --output reports/traces.json
reqvire traces --filter-type test-verification
reqvire traces --links-with-blobs

reqvire resources
reqvire resources --json --output reports/resources.json

reqvire submodels
reqvire submodels --from "API Authentication"
reqvire submodels --json --output reports/submodels.json

Change Impact Workflow

Change impact turns repository diffs into a review queue. Use it to find changed requirements, affected descendants, linked verifications, attached contracts, satisfied implementation artifacts, and governance context that should guide review order.

reqvire change-impact
reqvire change-impact --git-commit origin/main
reqvire change-impact --git-commit origin/main --json --output reports/impact.json

reqvire search --filter-risk high,critical --filter-status review
reqvire traces --json --output reports/traces.json
reqvire coverage --json --output reports/coverage.json

Start with changed high-risk or critical requirements.
Review attached contracts and child requirements before treating a change as isolated.
Use traces to find verification evidence that must be rerun or hardened.
Use coverage to confirm affected obligations still have implementation or evidence links.

Serve Explorer

Serve starts a local Explorer for the current workspace with model views, verification traces, coverage reports, resources, and ontology explorer output.

reqvire serve
reqvire serve --host 0.0.0.0 --port 3000

Ignore Files

.gitignore excludes files from structured parsing and from file relations.
.reqvireignore excludes files from structured parsing but still allows file relations to reference them.
Common repository docs such as README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE.md, SECURITY.md, and AI assistant instruction files are reserved and skipped as model files.

GitHub Workflows

Reqvire fits naturally into pull request checks and issue-comment workflows. Use pull request jobs for required validation and report artifacts; use comment-triggered jobs for review-time impact and trace questions that should not run on every push.

Pull Request Validation

This pattern validates the model, surfaces lint findings, writes JSON reports, and uploads the report folder as an artifact. Fetch full git history when change-impact needs to compare against the pull request base branch.

name: Reqvire PR Checks

on:
  pull_request:
    branches: [main]

jobs:
  reqvire:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Install Reqvire
        run: curl -fsSL https://raw.githubusercontent.com/reqvire-org/reqvire/main/scripts/install.sh | bash

      - name: Generate Reqvire reports
        run: |
          mkdir -p reports
          git fetch origin "${{ github.base_ref }}"
          reqvire validate --json --output reports/validate.json
          reqvire lint --auditable --json --output reports/lint.json
          reqvire coverage --json --output reports/coverage.json
          reqvire traces --json --output reports/traces.json
          reqvire change-impact --git-commit "origin/${{ github.base_ref }}" --json --output reports/impact.json

      - name: Upload Reqvire reports
        uses: actions/upload-artifact@v6
        with:
          name: reqvire-reports
          path: reports/

Issue Comment Commands

Comment workflows run only when a reviewer asks for them. The job must check out the pull request branch, compute the merge-base commit against the base branch, then pass that commit to change-impact.

/reqvire impactRun change-impact against the pull request merge base and comment with the report.

/reqvire tracesRun verification traces and comment with the report.

/reqvire coverageRun coverage and comment with the report.

name: Reqvire PR Commands

on:
  issue_comment:
    types: [created]

jobs:
  run-reqvire:
    if: |
      github.event.issue.pull_request != null &&
      (
        contains(github.event.comment.body, '/reqvire impact') ||
        contains(github.event.comment.body, '/reqvire traces') ||
        contains(github.event.comment.body, '/reqvire coverage')
      )
    runs-on: ubuntu-latest
    permissions:
      pull-requests: read
      issues: write
      contents: read

    steps:
      - name: Resolve pull request refs
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          HEAD_REF=$(gh pr view ${{ github.event.issue.number }} --json headRefName --jq '.headRefName')
          BASE_REF=$(gh pr view ${{ github.event.issue.number }} --json baseRefName --jq '.baseRefName')
          echo "HEAD_REF=$HEAD_REF" >> "$GITHUB_ENV"
          echo "BASE_REF=$BASE_REF" >> "$GITHUB_ENV"

      - name: Checkout pull request branch
        uses: actions/checkout@v6
        with:
          ref: ${{ env.HEAD_REF }}
          fetch-depth: 0

      - name: Compute merge base
        run: |
          git fetch origin "$BASE_REF"
          BASE_COMMIT=$(git merge-base "origin/$BASE_REF" HEAD)
          echo "BASE_COMMIT=$BASE_COMMIT" >> "$GITHUB_ENV"

      - name: Install Reqvire
        run: curl -fsSL https://raw.githubusercontent.com/reqvire-org/reqvire/main/scripts/install.sh | bash

      - name: Run requested report
        run: |
          if grep -q '/reqvire impact' <<< "${{ github.event.comment.body }}"; then
            reqvire change-impact --git-commit "$BASE_COMMIT" > reqvire-report.md
          elif grep -q '/reqvire traces' <<< "${{ github.event.comment.body }}"; then
            reqvire traces > reqvire-report.md
          elif grep -q '/reqvire coverage' <<< "${{ github.event.comment.body }}"; then
            reqvire coverage > reqvire-report.md
          fi

      - name: Comment with report
        uses: peter-evans/create-or-update-comment@v5
        with:
          issue-number: ${{ github.event.issue.number }}
          body-path: reqvire-report.md