Tetrix CLI

AI-powered architecture and code quality checks for your projects

Tetrix CLI automatically reviews your code changes for architecture violations, security issues, and best practices using AI-powered analysis. Perfect for local development and CI/CD pipelines.

✨ Features

• 🔍 AI-Powered Reviews - Intelligent code analysis using advanced AI models
• 🏗️ Architecture Validation - Enforces layering, separation of concerns, and design patterns
• 🔒 Security Checks - Detects security vulnerabilities and risky patterns
• 📋 Custom Rules - Define your own architecture rules and best practices
• 🚀 CI/CD Ready - Integrates seamlessly with GitHub Actions, GitLab CI, and more
• ⚡ Fast & Parallel - Reviews multiple files simultaneously
• 🎯 Zero Config - Works out of the box with sensible defaults
• 📊 Validation History - Track patterns, analyze failures, and measure improvement over time

🚀 Quick Start

Installation

# Install globally
npm install -g @tetrix-ai/cli

# Verify installation
tetrix --help

Initialize in Your Project

cd your-project
tetrix init

This creates a .tetrixci.yaml configuration file with default settings.

Authenticate

# Interactive mode (prompts for token)
tetrix auth

# Non-interactive (for CI/CD)
tetrix auth --token YOUR_API_TOKEN

Run Architecture Review

# Review current changes
tetrix review

# Review changes between branches
tetrix review --base origin/main --head HEAD

# Review from a diff file (useful for saving/sharing reviews)
git diff > my-changes.patch           # First, generate the diff file
tetrix review --diff-file my-changes.patch  # Then, review it

# Run specific process only
tetrix review --process architecture_review

# Silent mode (only verdict and issues)
tetrix review --silent

# Debug mode (detailed analysis)
tetrix review --debug

📋 Commands

tetrix init

Initialize Tetrix in your project. Creates .tetrixci.yaml configuration file.

tetrix init

tetrix auth

Authenticate with Tetrix API. Saves token locally for future use.

# Interactive mode (prompts for token)
tetrix auth

# Non-interactive (for CI/CD)
tetrix auth --token YOUR_API_TOKEN

tetrix review

Run architecture and quality checks on your code changes.

# Review current unstaged/staged changes
tetrix review

# Review changes between branches
tetrix review --base origin/main --head HEAD

# Review from a diff file
tetrix review --diff-file my-changes.patch

# Run specific process only
tetrix review --process architecture_review

# Silent mode (only show verdict and issues)
tetrix review --silent

# Debug mode (show detailed analysis)
tetrix review --debug

Options:

• --config <file> - Use custom config file (default: .tetrixci.yaml)
• --process <name> - Run specific process only (default: all processes)
• --base <ref> - Base git reference for diff
• --head <ref> - Head git reference for diff
• --diff-file <path> - Path to diff file
• --silent - Only show verdict and issue summary
• --debug - Enable debug mode (see below)

Debug Mode (--debug)

When --debug is enabled:

1. Stack traces - Shows full error stack traces when something fails
2. Audit logs - Writes detailed logs to .tetrix/logs/ for each file review:
   • Full prompt sent to the AI agent
   • Raw response received from the agent
   • Parse errors (if any)
   • Duration of each review

Useful for:

• Debugging agent response parsing issues
• Understanding why a file passed/failed
• Reporting bugs with full context

# Run with debug mode
tetrix review --debug

# Check the logs
ls .tetrix/logs/
cat .tetrix/logs/2024-12-05T*.log

tetrix size

Check file sizes for full-file review compatibility. Useful to verify files won't be skipped due to token limits when using mode: full or mode: project.

# Check a single file
tetrix size src/myfile.ts

# Check all staged files
tetrix size --staged

# Check files matching a pattern
tetrix size --pattern "src/**/*.ts"

# Check with process-specific limits (uses KB size)
tetrix size --staged --process documentation_review

Output example:

📏 File Size Analysis: src/myfile.ts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Lines:        245
   Characters:   8,432
   Est. Tokens:  ~2,409
   
   ✅ PASS: Within limits for full-file review
   └─ Max allowed: ~15,000 tokens

Options:

• [files...] - One or more file paths to check
• --staged - Check all staged files (git add)
• --pattern <glob> - Check files matching glob pattern
• --process <name> - Use process-specific knowledge base for limit calculation
• --config <file> - Path to config file

tetrix history

View validation history. Reports are automatically saved after each tetrix review.

# Show last 10 validations
tetrix history

# Show last N validations
tetrix history --limit 20

# Show only today's validations
tetrix history --today

# Show only failed validations
tetrix history --failures

# Filter by process name
tetrix history --process architecture_review

# Show detailed output (with IDs and duration)
tetrix history --verbose

# Export as JSON (for CI/scripting)
tetrix history --json

Output example:

📜 Tetrix Validation History
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  # │ Date       │ Time  │ Process              │ Verdict │ Issues │ Files
────┼────────────┼───────┼──────────────────────┼─────────┼────────┼──────
  1 │ 2024-12-04 │ 14:22 │ architecture_review  │ ✅ pass │      0 │   5
  2 │ 2024-12-04 │ 14:15 │ typescript_review    │ ❌ fail │      3 │   5
  3 │ 2024-12-04 │ 11:30 │ architecture_review  │ ❌ fail │      2 │   3

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Total: 3 validations │ Passed: 1 │ Failed: 2 │ Pass Rate: 33%

Options:

• --limit <n> - Number of reports to show (default: 10)
• --today - Show only today's validations
• --failures - Show only failed validations
• --process <name> - Filter by process name
• --verbose - Show detailed output with IDs and duration
• --json - Output as JSON

tetrix stats

Show aggregated statistics and patterns from validation history.

# Show overall statistics
tetrix stats

# Show top issues (most common patterns)
tetrix stats --top-issues

# Show violations grouped by knowledge base standard
tetrix stats --by-standard

# Show stats since specific date
tetrix stats --since 2024-12-01

# Export as JSON
tetrix stats --json

Output example:

📊 Tetrix Validation Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Overview (2024-12-01 to 2024-12-04)
  ─────────────────────────
  Total Validations:    47
  Pass Rate:            72%
  Total Issues Found:   89
  Estimated Tokens:     ~1.2M

  Most Common Issues
  ─────────────────────────
  1. Missing error handling         │ 15 occurrences │ 8 files
  2. Shell injection vulnerability  │ 12 occurrences │ 5 files
  3. Missing JSDoc documentation    │ 10 occurrences │ 10 files

Options:

• --top-issues - Show most common issues
• --by-standard - Group violations by knowledge base standard
• --since <date> - Start date (YYYY-MM-DD)
• --json - Output as JSON

tetrix report

View a specific validation report in detail.

# View report by ID (first 8 chars)
tetrix report abc12345

# View most recent report
tetrix report --latest

# Export as JSON
tetrix report abc12345 --json

Output example:

📋 Tetrix Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Report ID:     abc12345-6789-...
  Process:       architecture_review
  Date:          2024-12-04 14:15:32
  Duration:      8.3s
  Verdict:       ❌ FAIL

  Failed Files
  ─────────────────────────
  
  ❌ src/auth/service.ts
     ┌─────────────────────────────────────────────────────────────
     │ [🔴 HIGH] Shell command injection vulnerability
     │ → Use exec with array arguments instead
     │ Standard: CLI_CRITICAL_RULES_ONLY.md (CRITICAL-SEC-1)
     └─────────────────────────────────────────────────────────────

Options:

• <id> - Report ID (partial match supported, first 8 chars)
• --latest - Show most recent report
• --json - Output as JSON

⚙️ Configuration

The .tetrixci.yaml file controls what and how Tetrix reviews your code:

agent:
  id: tetrix-architecture-reviewer

# Reports configuration (optional)
reports:
  enabled: true              # Enable/disable report generation
  directory: .tetrix/reports # Report storage directory
  retention:
    max_reports: 100         # Keep last N reports
    max_days: 30             # Or keep reports for N days
  include_in_gitignore: true # Auto-add .tetrix/ to .gitignore

processes:
  # Diff mode (default) - fast, focused on changes only
  - name: architecture_review
    type: "architecture_review"
    mode: diff  # Only send git diff content
    strict: true  # Fail CI on violations
    concurrency: 5  # Review 5 files in parallel
    knowledge_base:
      - docs/ARCHITECTURE_RULES.md
    exclude:
      - "**/__tests__/**"
      - "**/*.test.ts"

  # Full mode - deeper analysis with full file context
  - name: documentation_review
    type: "architecture_review"
    mode: full  # Send entire file content
    max_file_tokens: 15000  # Optional: override calculated limit
    strict: false  # Advisory only
    concurrency: 3
    knowledge_base:
      - docs/DOCUMENTATION_STANDARDS.md

Configuration Options

agent

• id - AgentOS agent identifier

reports (optional)

• enabled - Enable/disable report generation (default: true)
• directory - Report storage directory (default: .tetrix/reports)
• retention.max_reports - Keep last N reports (default: 100)
• retention.max_days - Keep reports for N days
• include_in_gitignore - Auto-add .tetrix/ to .gitignore (default: true)

Reports are automatically generated after each tetrix review and stored as JSON files. Use tetrix history, tetrix stats, and tetrix report commands to view them.

processes

• name - Process identifier
• type - Process type (architecture_review)
• mode - Review mode: diff (default), full, or project
• max_file_tokens - Max tokens per file in full/project mode (default: ~15,000)
• max_files - Max files to review in project mode (default: 50)
• skip_large_files - In full/project mode: false (default, fail on large files) or true (skip with warning)
• strict - Fail on violations (true/false)
• concurrency - Parallel file reviews (default: 10)
• knowledge_base - List of markdown files with your rules
• include - File patterns to review (glob syntax)
• exclude - File patterns to skip (glob syntax)

Review Modes

| Mode | Description | Best For | |------|-------------|----------| | diff | Only sends git diff content (default) | Security checks, pattern detection, fast reviews | | full | Sends entire file content for changed files only | JSDoc validation, architecture coherence, deep analysis | | project | Scans ALL files matching patterns (ignores git diff) | Full audits, onboarding, compliance reviews |

Full/Project Mode Token Limits:

By default, full and project modes are strict - if any file exceeds the token limit, the process fails immediately. This ensures you don't accidentally skip important files.

# Strict (default): Fail if any file is too large
- name: documentation_review
  mode: full
  # skip_large_files: false  # default

# Lenient: Skip large files with warning, continue with others
- name: documentation_review
  mode: full
  skip_large_files: true

# Project mode: Audit ALL files (not just changed ones)
- name: full_audit
  mode: project
  max_files: 50        # Limit files to review (default: 50)
  skip_large_files: true
  knowledge_base:
    - docs/STANDARDS.md
  include:
    - "**/*.ts"

Use tetrix size to check file sizes before running full/project mode reviews.

🏗️ Use Cases

Local Development

Get instant feedback on your code before committing:

# Make changes to your code

# Review changes (auto-staging if enabled in config)
tetrix review

# Note: If your .tetrixci.yaml has git.auto_stage: true,
# the CLI will automatically stage changes before reviewing.
# Otherwise, stage manually first:
git add .
tetrix review

Diff file workflow:

# Generate diff file
git diff > my-changes.patch

# Review the diff
tetrix review --diff-file my-changes.patch

Pre-commit Hook

Add to .husky/pre-commit:

#!/bin/sh
tetrix review || exit 1

GitHub Actions

Protect Pull Requests (Most Important)

Use Case: Block merging PRs with architecture violations or security issues.

Add to .github/workflows/pr-quality-check.yml:

name: PR Quality Check

on:
  pull_request:
    branches: 
      - main        # Protect main branch
      - develop     # Protect develop branch

jobs:
  tetrix-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Need full history for diff
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Tetrix CLI
        run: npm install -g @tetrix-ai/cli
      
      - name: Authenticate
        run: tetrix auth --token "${{ secrets.TETRIX_API_TOKEN }}"
      
      - name: Review PR Changes
        run: |
          # Compare feature branch (HEAD) against base branch (e.g., main)
          # This reviews ONLY the changes being merged in this PR
          tetrix review --base origin/${{ github.base_ref }} --head HEAD
          
          # If Tetrix finds issues and your .tetrixci.yaml has strict: true,
          # the CLI will exit with code 1, causing this step to FAIL
          # GitHub will then block the merge until issues are fixed

How it blocks merges:

1. Tetrix finds critical issue → CLI exits with code 1
2. GitHub Action fails → Red X in PR checks
3. Merge blocked → "All checks must pass" requirement
4. Developer must fix → Push fixes, review runs again
5. No issues found → CLI exits with code 0 → Green checkmark → Merge allowed

What this does:

• ✅ Runs on every Pull Request to main or develop
• ✅ Compares PR branch vs target branch (e.g., feature/new-api vs main)
• ✅ Blocks merge if Tetrix finds critical issues (when strict: true)
• ✅ Shows review results in PR checks
• ❌ Prevents merging until all issues are resolved

Example PR Check Result:

✅ Build - Passed
✅ Tests - Passed  
❌ Tetrix Quality Check - Failed
   └─ Architecture violations found
   └─ Fix issues before merging

Protect Direct Pushes to Main

Use Case: Validate commits pushed directly to main (if allowed in your repo).

Add to .github/workflows/push-quality-check.yml:

name: Push Quality Check

on:
  push:
    branches:
      - main        # Run on pushes to main

jobs:
  tetrix-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 2  # Need at least 2 commits for diff
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Tetrix CLI
        run: npm install -g @tetrix-ai/cli
      
      - name: Authenticate
        run: tetrix auth --token "${{ secrets.TETRIX_API_TOKEN }}"
      
      - name: Review Latest Commit
        run: |
          # Compare current commit (HEAD) against previous commit (HEAD~1)
          # This reviews ONLY the changes in the latest push
          tetrix review --base HEAD~1 --head HEAD

What this does:

• ✅ Runs on every push to main branch
• ✅ Compares latest commit vs previous commit
• ✅ Reports issues but doesn't block (commit already pushed)
• ✅ Useful for monitoring and alerts

Advanced: Review Multiple Commits in Push

- name: Review All Commits in Push
  run: |
    # Compare against the commit before this push started
    # ${{ github.event.before }} = commit SHA before the push
    # HEAD = current commit after the push
    tetrix review --base ${{ github.event.before }} --head HEAD

What this does:

• ✅ Reviews ALL commits in a single push (if multiple commits pushed together)
• ✅ More comprehensive than HEAD~1 approach

Understanding Branch Comparisons

Pull Request (feature → main):

main:     A---B---C
                   \
feature:            D---E---F  (your PR)

Command: tetrix review --base origin/main --head HEAD
Compares: C (last commit in main) vs F (your latest changes)
Reviews: Only commits D, E, F (the PR changes)

Direct Push to Main:

main: A---B---C---D  (D is new push)
              ↑   ↑
           before after

Command: tetrix review --base HEAD~1 --head HEAD
Compares: C (previous commit) vs D (new commit)
Reviews: Only commit D (the push)

GitLab CI

Protect Merge Requests

Add to .gitlab-ci.yml:

tetrix-review:
  stage: test
  image: node:18
  rules:
    - if: $CI_MERGE_REQUEST_IID  # Only run on merge requests
  script:
    - npm install -g @tetrix-ai/cli
    - tetrix auth --token "$TETRIX_API_TOKEN"
    # Compare MR source branch vs target branch
    - tetrix review --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --head HEAD
    
    # If Tetrix finds issues (strict: true in config),
    # this script exits with code 1 → Pipeline FAILS → Merge BLOCKED

How it blocks merges:

1. Tetrix finds critical issue → CLI exits with code 1
2. GitLab pipeline fails → Red X in MR
3. Merge blocked → Pipeline must pass to merge
4. Developer fixes issues → Pushes changes → Pipeline runs again
5. No issues → CLI exits with code 0 → Green checkmark → Merge allowed

What this does:

• ✅ Runs only on Merge Requests (not on regular commits)
• ✅ Compares MR source branch vs target branch (e.g., feature vs main)
• ✅ Blocks merge if critical issues found (when strict: true)
• ❌ Prevents merging until all issues are resolved

Example MR Pipeline Result:

Stage: test
  ✅ unit-tests - Passed
  ✅ integration-tests - Passed
  ❌ tetrix-review - Failed (exit code 1)
     └─ CRITICAL-SEC-1: Shell injection found
     └─ Fix required before merge

GitHub Branch Protection Setup

To enforce Tetrix checks before merging:

1. Go to: Settings → Branches → Branch protection rules
2. Select branch: main
3. Enable: ✅ Require status checks to pass before merging
4. Select: ✅ Tetrix Quality Check (or your workflow name)
5. Enable: ✅ Require branches to be up to date

Now PRs cannot be merged until Tetrix review passes.

When to Use Each Approach

| Scenario | Trigger | Base | Head | Purpose | |----------|---------|------|------|---------| | PR to main | pull_request | origin/main | HEAD | Block merge if issues found | | PR to develop | pull_request | origin/develop | HEAD | Block merge if issues found | | Push to main | push | HEAD~1 | HEAD | Monitor latest commit | | Multi-commit push | push | ${{ github.event.before }} | HEAD | Monitor all pushed commits |

Recommendation: Use Pull Request protection (first row) as your primary quality gate.

🔧 Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | TETRIX_GATEWAY_URL | Override default gateway URL | No | | TETRIX_API_TOKEN | API authentication token | Yes* |

* Required for production use. Not needed if using tetrix auth login.

📊 Example Output

🔍 Tetrix Architecture Review
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 Reviewing 5 files...

✓ src/utils/helper.ts - PASS
✓ src/config/index.ts - PASS
✗ src/auth/service.ts - FAIL
  
  Issues found:
  
  🔴 HIGH - CRITICAL-SEC-1: Shell command injection vulnerability
      Line 45: Using string concatenation for shell commands
      
      Suggestion: Use exec with array arguments instead
      
  🟡 MEDIUM - CRITICAL-ERR-1: Missing error handling
      Line 67: External API call without try/catch
      
      Suggestion: Wrap fetch() in try/catch block

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VERDICT: fail
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ Review failed with 1 critical issue

🤖 MCP Server for AI Agents

Tetrix CLI includes a built-in MCP (Model Context Protocol) server that provides AI agents like Cursor and Claude Code with structured knowledge about Tetrix.

What is MCP?

The MCP server is NOT a wrapper for CLI commands (AI agents can already execute terminal commands directly). Instead, it's a knowledge base that teaches AI agents:

• What Tetrix is and why it matters
• How to configure .tetrixci.yaml correctly
• What commands to execute directly
• How to interpret and fix violations
• Best practices for different project types

Starting the MCP Server

tetrix mcp

This starts the MCP server in stdio mode (used by AI IDEs).

Cursor IDE Configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "tetrix": {
      "command": "tetrix",
      "args": ["mcp"]
    }
  }
}

Claude Code Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tetrix": {
      "command": "tetrix",
      "args": ["mcp"]
    }
  }
}

Available MCP Tools

| Tool | Description | |------|-------------| | get_overview | Introduction to Tetrix - start here | | get_cli_reference | All CLI commands with options | | search_docs | Search documentation by query | | explain_standard | Explain a rule violation | | get_config_example | Configuration examples by project type | | get_best_practices | Recommendations for different scenarios | | get_modes | Review modes explained (diff, full, project) |

Example AI Workflow

1. AI agent calls get_overview() to learn about Tetrix
2. AI agent uses get_config_example("typescript") to help configure
3. AI agent executes tetrix review directly in terminal
4. If violations found, AI uses explain_standard("RULE-ID") to understand

🤝 Contributing

See CONTRIBUTORS.md for development setup, architecture details, and contribution guidelines.

📝 License

MIT © Deskree Technologies Inc.

🔗 Links

• Documentation
• GitHub Repository
• Issue Tracker
• NPM Package

💡 Getting Help

• Documentation: docs.tetrix.ai
• Issues: GitHub Issues
• Email: [email protected]

Made with ❤️ by Tetrix AI