Package Exports

@contextium/cli
@contextium/cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@contextium/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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.