@contextium/cli

Contextium CLI

Command-line interface for Contextium that allows developers to fetch and pipe documentation to external AI tools.

Installation

# Build the CLI
npm run build

# Link for local development
npm link

Setup

1. Initialize a Project

# Navigate to your project directory
cd /path/to/your/project

# Initialize Contextium with your workspace and project
contextium init \
  --api-key YOUR_API_KEY \
  --workspace your-workspace-slug \
  --project your-project-slug \
  --api-url http://localhost:3001/api/v1

# Or use environment variable for API key
export CONTEXTIUM_API_KEY=your_api_key
contextium init --workspace your-workspace-slug --project your-project-slug

This creates:

• .contextiumrc - Configuration file
• .contextium-cache/ - Local cache directory
• Updates .gitignore to exclude cache directory

2. Sync Files

Download all project files to local cache:

# Sync all files
contextium sync

# Sync specific files
contextium sync README.md API_GUIDE.md

# Sync files with specific tags
contextium sync --tag foundation-context --tag always-include

# Force re-download all files
contextium sync --force

# Dry run to see what would be synced
contextium sync --dry-run

Usage

Check Status

Check which files are cached and up-to-date:

contextium status

Output:

Project: My Project
Project ID: abc-123
Workspace: my-workspace

✓ README.md v3 (up to date)
↓ API_GUIDE.md v2 (v5 available, 3 versions behind)
? SETUP.md (not cached)

2 file(s) need update - run 'contextium sync'
1 file(s) not cached - run 'contextium sync'

Output File Content

Output file content to stdout for piping to AI tools:

# Output all files
contextium cat --all

# Output specific files
contextium cat README.md API_GUIDE.md

# Output files with specific tags
contextium cat --tag always-include

# Include metadata headers
contextium cat --all --with-meta

# Output as JSON
contextium cat --all --format json

Pipe to External AI Tools

The primary use case - pipe documentation to AI tools like Cursor, Claude, or Copilot:

# Pipe all documentation to clipboard
contextium cat --all | pbcopy

# Pipe to Cursor
contextium cat --all | cursor --add-context

# Pipe foundation docs to Claude
contextium cat --tag foundation-context | claude --context

# Pipe specific files
contextium cat README.md API_GUIDE.md | cursor --add-context

Search Files

Search for files in your project:

# Search by filename or content
contextium search "authentication"

# Search with tag filter
contextium search "api" --tag backend

# Limit results
contextium search "guide" --limit 5

Configuration

The .contextiumrc file contains your project configuration:

{
  "api_key": "your-api-key",
  "api_url": "http://localhost:3001/api/v1",
  "project_id": "project-uuid",
  "workspace": "workspace-slug",
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "directory": ".contextium-cache",
    "max_size_mb": 100
  },
  "sync": {
    "auto": true,
    "on_command": ["build", "test"],
    "notify_changes": true,
    "interval": 300
  },
  "files": {
    "include": [],
    "exclude": ["DEPRECATED_*.md", "DRAFT_*.md"],
    "tags": ["foundation-context", "always-include"],
    "auto_include_tags": true
  }
}

Workflow Example

# 1. Initialize in your project
cd ~/projects/my-app
contextium init --workspace my-company --project my-app

# 2. Sync all documentation
contextium sync

# 3. Start coding with AI assistance
# Pipe all relevant docs to your AI tool
contextium cat --tag always-include | cursor --add-context

# 4. Update when docs change
contextium status  # Check for updates
contextium sync    # Download latest versions

Cache Management

The CLI caches files locally for faster access:

• Cache directory: .contextium-cache/
• TTL: 1 hour (configurable)
• Auto-syncs based on configuration
• Use --no-cache flag to bypass cache

Development

# Build
npm run build

# Watch mode
npm run dev

# Type check
npm run type-check

Architecture

The CLI is designed to be a lightweight bridge between your Contextium documentation repository and external AI coding tools:

Your Project
    ↓
Contextium CLI (fetch docs)
    ↓
Local Cache (.contextium-cache/)
    ↓
Pipe to AI Tool (Cursor, Claude, Copilot)
    ↓
AI-assisted Development

For more information, see the Platform Specification.