Convext CLI

Sync engineering rules and standards to your project from Convext.

npm: https://www.npmjs.com/package/@convext/cli

Installation

# Install globally
npm install -g @convext/cli

# Or use via npx (no install needed)
npx @convext/cli <command>

Quick Start

# 1. Configure your API token
convext config --token YOUR_TOKEN

# 2. Initialize your project
convext init

# 3. Sync rules and generate dotfiles
convext sync

Commands

sync - Sync engineering rules and generate IDE dotfiles

convext sync [options]

Options:
  -p, --project <slug>     Project slug to sync context for
  -l, --languages <langs>  Comma-separated languages (e.g., 'ruby,typescript')
  -f, --format <format>    Output format: claude (default), cursor, copilot, antigravity, or all
  -n, --dry-run            Preview changes without writing files
  -v, --verbose            Show detailed debug output
  --hooks                  Generate enforcement hooks for Claude Code
  --telemetry              Upload local telemetry to Convext cloud
  --skip-plans             Skip syncing plans and tasks (only sync context/rules)

Generated files:

• CLAUDE.md - Claude Code instructions
• .cursorrules - Cursor IDE rules
• .github/copilot-instructions.md - GitHub Copilot instructions

check - Validate compliance with Convext rules

convext check [options]

Options:
  -s, --strict    Fail (exit code 1) if files are out of sync
  -q, --quiet     Suppress output, only return exit code

init - Initialize and register project with Convext

convext init [options]

Options:
  -n, --name <name>    Project name (default: current directory name)
  -o, --org <name>     Organization name or ID

Creates .convext/config.json with project configuration.

config - Manage CLI configuration

convext config --token YOUR_TOKEN    # Set API token
convext config --url https://...     # Set custom API URL
convext config --show                # Show current config

mcp - Configure MCP for your editor/agent

Automatically detect and configure MCP (Model Context Protocol) for your AI coding assistant.

convext mcp [options]

Options:
  -e, --editor <name>  Specify editor (claude-code, cursor, windsurf, vscode)
  -f, --fix            Auto-fix configuration without prompting
  -s, --status         Show MCP configuration status for all editors

Examples:

# Check MCP status across all editors
convext mcp --status

# Configure MCP for detected/selected editor
convext mcp

# Configure MCP for a specific editor
convext mcp --editor cursor

# Auto-fix without prompts
convext mcp --fix

Supported editors:

• Claude Code - Anthropic's CLI
• Cursor - AI-powered IDE
• Windsurf - Codeium's IDE
• VS Code - With MCP extension

whoami - Show configured user and organization

convext whoami

Configuration

Authentication

# Config file (~/.convext/config.json)
convext config --token YOUR_TOKEN

# Or via environment variable
export CONVEXT_TOKEN="cc_live_..."

Custom API URL

convext config --url https://your-server.com

Workflows

Pre-commit Hook

Automatically check compliance before committing:

#!/bin/sh
# .git/hooks/pre-commit

# Ensure rules are in sync (don't fail build)
npx @convext/cli check || echo "Warning: Rules may be out of date"

Or stricter version:

#!/bin/sh
# .git/hooks/pre-commit

  npx @convext/cli sync 2>/dev/null || true

CI/CD Integration

GitHub Actions

name: Convext Compliance

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npx @convext/cli check --strict
        env:
          CONVEXT_TOKEN: ${{ secrets.CONVEXT_TOKEN }}

Pre-push Hook

npx @convext/cli check || exit 1

Project Configuration

After running init, a .convext/config.json file is created:

{
  "slug": "my-org/my-project",
  "name": "my-project",
  "repoUrl": "https://github.com/myorg/my-project"
}

This file should be committed to version control so team members share the same project context.

File Structure

~/.convext/           # Global config directory
  config.json         # API token and URL

.convext/             # Project-specific directory (commit to repo)
  config.json         # Project slug and metadata
  plans/              # Synced plan files
  tasks/              # Synced task files
  active_task.json    # Currently active task (when working)

CLAUDE.md             # Generated file for Claude Code
.cursorrules          # Generated file for Cursor
.github/
  copilot-instructions.md  # Generated file for GitHub Copilot

License

MIT