The Convext CLI tool (convext) is the primary interface for developers to interact with the Convext platform. It handles project registration, rule synchronization, and compliance checking.
Quick Links
Installation
Requires Node.js 18 or higher. View on npm
npm install -g @convext/cli
# Or run via npx (no install needed)
npx @convext/cli --help
Configuration
The CLI needs an API token to authenticate. You can provide this in three ways (in order of precedence):
-
Command Line Flag
convext sync --token cc_live_...
-
Environment Variable (Recommended for CI/CD)
export CONVEXT_TOKEN="cc_live_..."
-
Config File (Recommended for local dev)
convext config --token cc_live_...
Stored in
~/.convext/config.json
sync
Downloads rules and standards for the current project and generates IDE configuration files.
Options
--project <id>: Override project ID (defaults to .convext.json)--dry-run: Show what would happen without writing files--force: Overwrite existing configuration files without prompting
Generated Files
CLAUDE.md: Context for Claude Code.cursorrules: Rules for Cursor IDE.github/copilot-instructions.md: Instructions for GitHub Copilot
check
Validates that the local project is in sync with Convext and complies with rules.
Options
--strict: Fail (exit code 1) if any files are out of sync or modified--quiet: Suppress output, only return exit code
Use in CI/CD: Run convext check --strict in your CI pipeline to ensure no one commits code without the latest rules.
init
Registers the current directory as a project in Convext.
Interactive prompts will guide you to:
- Select an Organization
- Confirm the Project Name (defaults to directory name)
Creates a .convext.json file.
config
Manages local configuration.
convext config --list
whoami
Displays the currently authenticated user and organization context.
Bootstrapping Workflows
The CLI can also bootstrap new projects with best-practice templates.
Ruby on Rails
Creates a new Rails 8 app with Tailwind, PostgreSQL, and standard configuration.
Next.js
Creates a Next.js app with TypeScript, Tailwind, and ESLint.
CI/CD Integration
GitHub Actions
Add this step to your workflow to enforce rules:
- name: Check Convext compliance
env:
CONVEXT_TOKEN: ${{ secrets.CONVEXT_TOKEN }}
run: npx @convext/cli check --strict
Advanced Usage
Ignoring Files
You can prevent Convext from overwriting specific files by adding a .convextignore file:
.cursorrules
Custom Config Path
Specify a custom configuration file location:
Troubleshooting
Error: "Project not found"
Ensure .convext.json exists in the current directory and the ID matches a project you have access to.
Error: "Unauthorized"
Your token may be invalid or expired. Generate a new one in Settings and run convext config --token NEW_TOKEN.
Changes are overwritten
Convext manages CLAUDE.md and .cursorrules. Do not edit them directly. Instead, update the Rules/Standards in the web UI.