@zebralabs/context-cli

Install engineering standards into your repository. AI remembers forever.

Context CLI is the command-line tool for installing and managing Context Packs — professional engineering standards that teach your AI tools (Cursor, Claude) how to generate consistent, standards-compliant output.

What is Context CLI?

AI coding assistants are fast, but they generate inconsistent output. Without standards, you spend time fixing AI mistakes instead of building features.

Context Packs solve this by injecting professional standards directly into your repository. Once installed, AI automatically follows your rules — no re-explaining, no drift, consistent output every time.

Key Benefits

• ✅ Standards live in your repo — Version-controlled, reviewable, evolvable
• ✅ Automatic enforcement — AI reads standards automatically, no activation needed
• ✅ Modular knowledge — Install only what you need, add more over time
• ✅ Built for AI tools — Designed for how Cursor and Claude actually work

Learn more: Visit zebralabs.io/context-packs for product overview, available packs, and purchasing.

Quick Start

1. Install the CLI

npm install -g @zebralabs/context-cli

2. Install Your First Pack

After purchasing a pack, you'll receive a download link and authentication token. Install it:

ctx pack install pack-01-documentation-management \
  --registry https://www.zebralabs.io/api \
  --token YOUR_TOKEN_HERE

3. Verify Installation

ctx list

You should see your installed pack listed. The pack is now part of your repository and works automatically with Cursor and Claude.

4. Start Using

Ask Cursor or Claude to generate documentation following your standards:

Generate a component specification following our documentation standards

AI will automatically use your installed standards — no re-explaining needed.

Need a pack? Browse available packs at zebralabs.io/context-packs

Commands

ctx help

Show help information and command usage.

ctx help

ctx pack install <packId>

Install a context pack into your repository.

Options:

• --repo-root <path> — Repository root directory (default: auto-detect)
• --mode <SkipExisting|Overwrite> — File merge mode (default: SkipExisting)
• --zip <path> — Install from local ZIP file
• --registry <url> — Registry URL for downloading packs
• --token <token> — Authentication token for registry
• --version <x.y.z> — Specific pack version (default: latest)

Examples:

Install from registry (requires token):

ctx pack install pack-01-documentation-management \
  --registry https://www.zebralabs.io/api \
  --token YOUR_TOKEN

Install specific version:

ctx pack install pack-01-documentation-management \
  --registry https://www.zebralabs.io/api \
  --token YOUR_TOKEN \
  --version 0.4.0

Install from local ZIP (for testing):

ctx pack install pack-01-documentation-management \
  --zip ./pack-01-documentation-management-v0.4.0.zip

What happens:

• Pack files are extracted and merged into docs/practices-and-standards/
• Cursor rules (.cursor/rules/) are copied to repository root
• Cursor skills (.cursor/skills/) are copied to repository root
• CLAUDE.md is copied to repository root
• context.yaml is created/updated with pack information

ctx list

List all installed context packs and their contributions.

ctx list

Output:

Installed Context Packs
-----------------------

- pack-01-documentation-management @ 0.4.0
  Contributes:
    - docs/practices-and-standards/01-engineering-practices/01-documentation-methodology
    - docs/practices-and-standards/01-engineering-practices/00-methodologies

Options:

• --context-yaml <path> — Path to context.yaml file (default: auto-detect)

ctx compile

Compile standards from installed packs into consolidated outputs.

Options:

• --pack <packId> — Compile a specific pack only
• --context-yaml <path> — Path to context.yaml file (default: auto-detect)

Examples:

Compile all installed packs:

ctx compile

Compile a specific pack:

ctx compile --pack pack-01-documentation-management

Output:

• docs/practices-and-standards/.compiled/system-prompt.md — Consolidated standards
• docs/practices-and-standards/.compiled/sources.md — Source file list
• docs/practices-and-standards/.compiled/report.md — Compilation report

Pack-specific compilation: When using --pack, outputs are generated in the pack directory:

• docs/practices-and-standards/packs/<pack-id>/.cursor/rules/ — Cursor rules
• docs/practices-and-standards/packs/<pack-id>/.cursor/skills/ — Cursor skills
• docs/practices-and-standards/packs/<pack-id>/CLAUDE.md — Claude instructions
• docs/practices-and-standards/packs/<pack-id>/CONSOLIDATED-STANDARDS.md — Human-readable standards

ctx validate

Validate your context.yaml configuration and installed packs.

ctx validate

Checks:

• Schema version compatibility
• Installed pack manifests exist
• Precedence list references valid packs
• Pack file structure integrity

Options:

• --context-yaml <path> — Path to context.yaml file (default: auto-detect)

ctx version

Show the CLI version.

ctx version
# or
ctx -v
# or
ctx --version

How It Works

Repository Structure

After installing a pack, your repository structure looks like:

your-repo/
├── .cursor/
│   ├── rules/              # Cursor rules (auto-loaded)
│   │   ├── index.md
│   │   └── doc-process.md
│   └── skills/             # Cursor skills (on-demand)
│       └── Domain Discovery Process/
│           └── SKILL.md
├── CLAUDE.md               # Claude instructions
├── docs/
│   └── practices-and-standards/
│       ├── context.yaml    # Pack registry and configuration
│       ├── 01-engineering-practices/
│       │   ├── 00-methodologies/
│       │   └── 01-documentation-methodology/
│       └── packs/
│           └── pack-01-documentation-management/
│               ├── pack.yaml
│               └── ...
└── ...

Context Configuration

The context.yaml file tracks installed packs and their precedence:

schema: context-install/v1
registry: https://www.zebralabs.io/api

installed_packs:
  - id: pack-01-documentation-management
    version: 0.4.0
    manifest: docs/practices-and-standards/packs/pack-01-documentation-management/pack.yaml

precedence:
  - pack-01-documentation-management

Precedence: When multiple packs define conflicting rules, packs listed earlier in precedence take priority.

Integration with AI Tools

Cursor:

• Rules in .cursor/rules/ are automatically loaded — AI follows them in every conversation
• Skills in .cursor/skills/ are available on-demand — invoke by name when needed
• Methodology files in docs/practices-and-standards/ are indexed automatically

Claude:

• CLAUDE.md provides consolidated standards at repository root
• Methodology files can be referenced in conversations
• Standards are version-controlled with your code

Examples & Workflows

Workflow 1: First-Time Installation

# 1. Install CLI
npm install -g @zebralabs/context-cli

# 2. Install pack (after purchase)
ctx pack install pack-01-documentation-management \
  --registry https://www.zebralabs.io/api \
  --token YOUR_TOKEN

# 3. Verify
ctx list

# 4. Start using with Cursor/Claude
# AI now automatically follows your standards

Workflow 2: Updating a Pack

# Install newer version
ctx pack install pack-01-documentation-management \
  --registry https://www.zebralabs.io/api \
  --token YOUR_TOKEN \
  --version 0.5.0 \
  --mode Overwrite

# Recompile to regenerate assets
ctx compile --pack pack-01-documentation-management

Workflow 3: Local Development

# Install from local ZIP (for pack development/testing)
ctx pack install pack-01-documentation-management \
  --zip ./my-pack-v0.1.0.zip \
  --mode Overwrite

# Compile to test asset generation
ctx compile --pack pack-01-documentation-management

Workflow 4: Multiple Packs

# Install first pack
ctx pack install pack-01-documentation-management \
  --registry https://www.zebralabs.io/api \
  --token YOUR_TOKEN

# Install second pack (when available)
ctx pack install pack-02-pr-review \
  --registry https://www.zebralabs.io/api \
  --token YOUR_TOKEN

# Set precedence (edit context.yaml manually or via future command)
# Then compile all packs
ctx compile

Troubleshooting

"Could not find context.yaml"

Problem: CLI can't locate context.yaml in your repository.

Solutions:

• Ensure you're running commands from your repository root
• Use --context-yaml <path> to specify the path explicitly
• Check that context.yaml exists in docs/practices-and-standards/ or practices-and-standards/

"Pack manifest not found"

Problem: Installed pack's pack.yaml file is missing.

Solutions:

• Reinstall the pack: ctx pack install <pack-id> --mode Overwrite
• Check that the pack directory exists in docs/practices-and-standards/packs/

"Missing required --token for registry install"

Problem: Registry installation requires authentication token.

Solutions:

• Ensure you have a valid token from your pack purchase
• Use --token YOUR_TOKEN flag
• For local testing, use --zip <path> instead

Installation Files Skipped

Problem: Files weren't copied during installation.

Solutions:

• Check installation mode: --mode SkipExisting skips existing files
• Use --mode Overwrite to replace existing files
• Check merge report in docs/practices-and-standards/.install/

Compilation Errors

Problem: ctx compile fails with module errors.

Solutions:

• Ensure you're running from the repository root
• Check Node.js version (requires Node.js 18+)
• Verify all pack files are intact: ctx validate
• Try compiling a specific pack: ctx compile --pack <pack-id>

Advanced Usage

Custom Pack Development

To develop your own packs:

1. Create pack structure following the standard format
2. Include pack.yaml manifest with contributes.roots
3. Include install.ps1 installer script
4. Test installation: ctx pack install <pack-id> --zip <path>
5. Test compilation: ctx compile --pack <pack-id>

Precedence Configuration

Edit docs/practices-and-standards/context.yaml to set pack precedence:

precedence:
  - pack-01-documentation-management  # Highest priority
  - pack-02-pr-review                 # Lower priority

Packs listed earlier take precedence when rules conflict.

Custom Registry

Use a custom registry for private or internal packs:

ctx pack install my-pack \
  --registry https://my-company.com/api \
  --token INTERNAL_TOKEN

Or set default registry in context.yaml:

registry: https://my-company.com/api

What's to Come

We're actively developing new features to make Context CLI even more powerful. Here's what's coming:

Enhanced Compilation Engine

• Rule Extraction — Automatic extraction of structured rules from markdown documents using @context.rules markers
• Conflict Detection — Intelligent detection of conflicting rules across multiple packs
• Semantic Conflict Resolution — Beyond ID-based conflicts, detect when rules semantically conflict
• Custom Documentation Support — Include your own custom standards alongside installed packs
• Change Tracking — Only recompile what's changed since last compilation

Multi-Pack Improvements

• Interactive Conflict Resolution — Guided workflow for resolving conflicts between packs
• Granular Precedence — Set precedence at rule level, not just pack level
• Conflict Reports — Detailed reports showing all conflicts and resolutions
• Pack Dependencies — Declare dependencies between packs

Developer Experience

• Precedence Management — CLI commands to manage pack precedence without editing YAML
• Pack Updates — ctx pack update command to update all packs to latest versions
• Pack Removal — ctx pack uninstall to cleanly remove packs
• Better Error Messages — More helpful error messages with suggested fixes
• Progress Indicators — Visual feedback during long operations

Integration Enhancements

• GitHub Copilot Support — Generate .github/copilot-instructions.md from compiled standards
• VS Code Integration — VS Code extension for managing packs and standards
• CI/CD Integration — Validate standards in CI pipelines
• Diff Viewing — See what changed when updating packs

Performance & Reliability

• Incremental Compilation — Faster compilations by only processing changed files
• Parallel Processing — Process multiple packs in parallel
• Caching — Cache compilation results for faster subsequent runs
• Validation Improvements — More comprehensive validation with better error reporting

Documentation & Learning

• Interactive Tutorial — Guided walkthrough for first-time users
• Pack Marketplace — Browse and discover packs from the CLI
• Examples Library — Curated examples of custom packs and configurations

Have ideas or feedback? We'd love to hear from you! Visit zebralabs.io/context-packs to share your thoughts.

Links & Resources

• Product Website: zebralabs.io/context-packs
• Available Packs: Browse packs and purchase at zebralabs.io/context-packs
• Support: Contact support through the website

License

MIT License — see LICENSE file for details.

Ready to get started? Install the CLI and visit zebralabs.io/context-packs to browse available packs.