---
title: CLI Guide
description: Command-line interface for TraceRTM - manage requirements from your terminal
keywords: [cli, command line, terminal, bash, shell, automation]
audience: user
difficulty: intermediate
---

import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';

# CLI Guide

The TraceRTM CLI provides powerful command-line access to all traceability features.

## Installation

<Tabs items={['Homebrew (macOS)', 'apt (Ubuntu/Debian)', 'Binary Download', 'From Source']}>
  <Tab value="Homebrew (macOS)">
    ```bash
    brew tap tracertm/tap
    brew install tracertm
    ```
  </Tab>

  <Tab value="apt (Ubuntu/Debian)">
    ```bash
    curl -fsSL https://tracertm.io/install.sh | sudo bash
    ```
  </Tab>

  <Tab value="Binary Download">
    Download from [GitHub Releases](https://github.com/tracertm/tracertm/releases):

    ```bash
    # macOS ARM64
    curl -LO https://github.com/tracertm/tracertm/releases/latest/download/tracertm-darwin-arm64.tar.gz
    tar xzf tracertm-darwin-arm64.tar.gz
    sudo mv tracertm /usr/local/bin/

    # Linux AMD64
    curl -LO https://github.com/tracertm/tracertm/releases/latest/download/tracertm-linux-amd64.tar.gz
    tar xzf tracertm-linux-amd64.tar.gz
    sudo mv tracertm /usr/local/bin/
    ```
  </Tab>

  <Tab value="From Source">
    ```bash
    git clone https://github.com/tracertm/tracertm-cli.git
    cd tracertm-cli
    make build
    sudo make install
    ```
  </Tab>
</Tabs>

### Verify installation

```bash
tracertm version
# Output: tracertm version 1.0.0
```

## Quick Start

<Steps>
  <Step>
    ### Authenticate

    ```bash
    tracertm login

    # Follow prompts:
    # Email: user@example.com
    # Password: ********
    # ✓ Authenticated successfully
    ```

    **Or use API key**:

    ```bash
    export TRACERTM_API_KEY="your-api-key"

    # Or configure in config file
    tracertm config set api_key "your-api-key"
    ```
  </Step>

  <Step>
    ### Create project

    ```bash
    tracertm project create \
      --name "My Project" \
      --key "MYPROJ" \
      --description "Project description"

    # Output:
    # ✓ Created project: proj-abc123
    # Key: MYPROJ
    # URL: https://app.tracertm.io/projects/proj-abc123
    ```
  </Step>

  <Step>
    ### Create requirement

    ```bash
    tracertm requirement create \
      --project MYPROJ \
      --type FR \
      --title "User authentication" \
      --priority MUST

    # Output:
    # ✓ Created requirement: MYPROJ-FR-1
    ```
  </Step>

  <Step>
    ### Create link

    ```bash
    tracertm link create \
      --source MYPROJ-FR-1 \
      --target MYPROJ-BR-1 \
      --type satisfies

    # Output:
    # ✓ Linked MYPROJ-FR-1 -> MYPROJ-BR-1 (satisfies)
    ```
  </Step>

  <Step>
    ### Generate matrix

    ```bash
    tracertm matrix generate \
      --project MYPROJ \
      --output rtm.pdf

    # Output:
    # Generating traceability matrix...
    # ✓ Matrix saved to rtm.pdf
    ```
  </Step>
</Steps>

## Core Commands

### `tracertm project`

Manage projects:

```bash
# List projects
tracertm project list
tracertm project ls  # Alias

# Create project
tracertm project create \
  --name "Project Name" \
  --key "PROJ" \
  --description "Optional description"

# Get project details
tracertm project get PROJ
tracertm project show PROJ  # Alias

# Update project
tracertm project update PROJ \
  --description "New description" \
  --settings '{"require_approval": true}'

# Delete project
tracertm project delete PROJ
tracertm project rm PROJ  # Alias
```

### `tracertm requirement`

Manage requirements:

```bash
# Create requirement
tracertm requirement create \
  --project PROJ \
  --type FR \
  --title "Requirement title" \
  --description "Detailed description" \
  --priority MUST \
  --status draft

# List requirements
tracertm requirement list --project PROJ
tracertm requirement ls PROJ  # Shorthand

# Filter requirements
tracertm requirement list PROJ \
  --type FR \
  --status approved \
  --priority MUST,SHOULD

# Get requirement details
tracertm requirement get PROJ-FR-1
tracertm req get PROJ-FR-1  # Alias

# Update requirement
tracertm requirement update PROJ-FR-1 \
  --status approved \
  --priority MUST

# Delete requirement
tracertm requirement delete PROJ-FR-1
```

### `tracertm link`

Manage traceability links:

```bash
# Create link
tracertm link create \
  --source PROJ-FR-1 \
  --target PROJ-BR-1 \
  --type satisfies \
  --rationale "FR implements BR"

# List links
tracertm link list PROJ-FR-1

# List by type
tracertm link list PROJ-FR-1 --type satisfies

# Delete link
tracertm link delete <link-id>
```

### `tracertm baseline`

Manage baselines:

```bash
# Create baseline
tracertm baseline create \
  --project PROJ \
  --name "v1.0.0" \
  --description "Release 1.0.0" \
  --freeze

# List baselines
tracertm baseline list --project PROJ

# Compare baselines
tracertm baseline diff v1.0.0

# Compare two baselines
tracertm baseline diff v1.0.0 v2.0.0

# Show baseline details
tracertm baseline show v1.0.0
```

### `tracertm matrix`

Generate traceability matrices:

```bash
# Generate matrix (PDF)
tracertm matrix generate \
  --project PROJ \
  --output rtm.pdf

# Generate Excel matrix
tracertm matrix generate PROJ \
  --format xlsx \
  --output rtm.xlsx

# Interactive HTML matrix
tracertm matrix generate PROJ \
  --format html \
  --interactive \
  --output rtm.html

# Filtered matrix
tracertm matrix generate PROJ \
  --filter "priority=MUST" \
  --source-type BR \
  --target-type FR,TC
```

## Analysis Commands

### Coverage analysis

```bash
# Test coverage
tracertm coverage test --project PROJ

# Output:
# Test Coverage Report
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Total Requirements: 45
# With Tests: 41 (91%)
# Without Tests: 4 (9%)
#
# Missing Coverage:
#   PROJ-FR-23: User profile editing
#   PROJ-FR-45: Password reset
#   PROJ-NFR-12: API rate limiting
#   PROJ-NFR-15: Data encryption

# Design coverage
tracertm coverage design --project PROJ

# Implementation coverage
tracertm coverage code --project PROJ
```

### Gap analysis

```bash
tracertm analyze gaps --project PROJ

# Output:
# Gap Analysis Report
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# Untested Requirements (4):
#   PROJ-FR-23: No test cases
#   PROJ-FR-45: No test cases
#
# Orphaned Tests (2):
#   PROJ-TC-156: Not linked to requirement
#   PROJ-TC-203: Not linked to requirement
#
# Missing Design (3):
#   PROJ-FR-12: No design document
```

### Impact analysis

```bash
tracertm analyze impact PROJ-FR-1

# Output:
# Impact Analysis: PROJ-FR-1
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# Affects 8 items:
#   SD-5: System design (implements)
#   SD-6: Database design (implements)
#   CM-23: auth_service.py (code_in)
#   CM-24: user_model.py (code_in)
#   TC-45: Test login flow (verifies)
#   TC-46: Test invalid credentials (verifies)
#   TC-47: Test session timeout (verifies)
#   ISS-12: Login bug (related_to)
```

## Import/Export

### Import from CSV

```bash
tracertm import csv \
  --project PROJ \
  --file requirements.csv \
  --map "title=Title,description=Description,priority=Priority"

# With preview
tracertm import csv requirements.csv \
  --project PROJ \
  --dry-run
```

### Import from Excel

```bash
tracertm import excel \
  --project PROJ \
  --file requirements.xlsx \
  --sheet "Requirements"
```

### Import from Jira

```bash
tracertm import jira \
  --project PROJ \
  --jira-url https://yourcompany.atlassian.net \
  --jira-project JIRAPROJ \
  --api-token $JIRA_TOKEN
```

### Export

```bash
# Export to CSV
tracertm export csv \
  --project PROJ \
  --output requirements.csv

# Export to Excel
tracertm export excel \
  --project PROJ \
  --output requirements.xlsx \
  --include-links

# Export to JSON
tracertm export json \
  --project PROJ \
  --output project.json
```

## Automation & Scripting

### Batch operations

```bash
# Create multiple requirements from file
cat requirements.txt | while read line; do
  tracertm requirement create \
    --project PROJ \
    --type FR \
    --title "$line"
done

# Update multiple requirements
tracertm requirement list PROJ --type FR --format json \
  | jq -r '.[] | .id' \
  | xargs -I {} tracertm requirement update {} --status approved
```

### CI/CD integration

```bash
#!/bin/bash
# .github/workflows/update-traceability.sh

# Link commits to requirements
git log --oneline HEAD~1..HEAD | while read commit; do
  # Extract requirement IDs (e.g., "PROJ-FR-1: Add feature")
  req_id=$(echo "$commit" | grep -oE 'PROJ-[A-Z]+-[0-9]+')

  if [ -n "$req_id" ]; then
    tracertm requirement update "$req_id" \
      --custom-field "last_commit=$commit"
  fi
done

# Import test results
pytest --junitxml=results.xml
tracertm import test-results \
  --project PROJ \
  --format junit \
  --file results.xml

# Check coverage threshold
coverage=$(tracertm coverage test PROJ --format json | jq '.percentage')
if (( $(echo "$coverage < 90" | bc -l) )); then
  echo "Coverage $coverage% below threshold"
  exit 1
fi
```

### Watch mode

```bash
# Monitor and auto-update
tracertm watch PROJ \
  --on-file-change "*.md" \
  --sync requirements/

# Auto-link code to requirements
tracertm watch PROJ \
  --on-file-change "src/**/*.py" \
  --link-code
```

## Configuration

### Config file

Location: `~/.tracertm/config.yaml`

```yaml
# Default settings
default_project: PROJ
api_key: your-api-key
base_url: https://api.tracertm.io/v1

# Output format
output:
  format: table  # table, json, yaml, csv
  color: true
  quiet: false

# Pagination
pagination:
  per_page: 25

# Editor
editor: vim

# Custom fields
custom_fields:
  component: [Auth, API, UI, Database]
  priority: [MUST, SHOULD, COULD, WONT]
```

### Environment variables

```bash
export TRACERTM_API_KEY="your-api-key"
export TRACERTM_BASE_URL="https://api.tracertm.io/v1"
export TRACERTM_PROJECT="PROJ"
export TRACERTM_EDITOR="code --wait"
```

## Output Formats

<Tabs items={['Table', 'JSON', 'YAML', 'CSV']}>
  <Tab value="Table">
    ```bash
    tracertm requirement list PROJ --format table

    # Output:
    # ID          Type  Title                      Priority  Status
    # ─────────────────────────────────────────────────────────────
    # PROJ-FR-1   FR    User authentication        MUST      approved
    # PROJ-FR-2   FR    Password reset             SHOULD    draft
    # PROJ-NFR-1  NFR   Response time < 200ms      MUST      approved
    ```
  </Tab>

  <Tab value="JSON">
    ```bash
    tracertm requirement list PROJ --format json

    # Output:
    [
      {
        "id": "PROJ-FR-1",
        "type": "FR",
        "title": "User authentication",
        "priority": "MUST",
        "status": "approved"
      }
    ]
    ```
  </Tab>

  <Tab value="YAML">
    ```bash
    tracertm requirement list PROJ --format yaml

    # Output:
    - id: PROJ-FR-1
      type: FR
      title: User authentication
      priority: MUST
      status: approved
    ```
  </Tab>

  <Tab value="CSV">
    ```bash
    tracertm requirement list PROJ --format csv

    # Output:
    # id,type,title,priority,status
    # PROJ-FR-1,FR,User authentication,MUST,approved
    # PROJ-FR-2,FR,Password reset,SHOULD,draft
    ```
  </Tab>
</Tabs>

## Interactive Mode

```bash
# Start interactive shell
tracertm shell

# Prompt appears:
tracertm> project list
tracertm> requirement create --project PROJ --type FR --title "New requirement"
tracertm> link create --source PROJ-FR-1 --target PROJ-BR-1
tracertm> exit
```

## Aliases

Create command aliases in `~/.tracertm/aliases.yaml`:

```yaml
# Shortcuts
aliases:
  req: requirement
  proj: project
  ls: list
  rm: delete
  cr: create
  up: update

# Custom commands
  my-projects: project list --filter owner=me
  urgent: requirement list --priority MUST --status draft
  coverage-report: |
    coverage test --project $1 &&
    coverage design --project $1 &&
    analyze gaps --project $1
```

Usage:

```bash
tracertm req ls PROJ  # Same as: tracertm requirement list PROJ
tracertm urgent PROJ  # List urgent requirements
tracertm coverage-report PROJ  # Run full coverage report
```

## Tips & Tricks

<Callout type="tip" title="Productivity Hacks">
**1. Shell completion**:

```bash
# Bash
tracertm completion bash > /etc/bash_completion.d/tracertm

# Zsh
tracertm completion zsh > "${fpath[1]}/_tracertm"

# Fish
tracertm completion fish > ~/.config/fish/completions/tracertm.fish
```

**2. Fuzzy search with fzf**:

```bash
# Interactive requirement selection
tracertm requirement list PROJ --format json \
  | jq -r '.[] | "\(.id): \(.title)"' \
  | fzf \
  | cut -d: -f1 \
  | xargs tracertm requirement get
```

**3. Template requirements**:

```bash
# Create template
tracertm requirement create \
  --project PROJ \
  --type FR \
  --template auth \
  --title "OAuth login" \
  --expand

# Expands from template with pre-filled fields
```
</Callout>

## Troubleshooting

### Authentication issues

```bash
# Clear cached credentials
tracertm logout

# Re-authenticate
tracertm login

# Verify token
tracertm whoami
```

### Connection issues

```bash
# Test API connection
tracertm ping

# Check API status
tracertm status

# Use different API endpoint
tracertm --base-url https://custom-api.com project list
```

### Debug mode

```bash
# Enable verbose logging
tracertm --debug requirement list PROJ

# Save debug logs
tracertm --debug --log-file debug.log requirement create ...
```

## Next Steps

- [API Reference](/api) - REST API documentation
- [Python SDK](/sdk/python) - Programmatic access
- [Automation Guide](/user/guides) - Advanced scripting

<Callout type="info">
**Questions?** Check [CLI GitHub Issues](https://github.com/tracertm/cli/issues) or join [Discord #cli-help](https://discord.gg/tracertm)
</Callout>
