Back to Documentation

Getting Started

Set up Convext to enforce engineering standards across your organization.

What is Convext?

Convext is a centralized "source of truth" system for engineering rules, technology standards, and project context. It helps teams maintain consistent coding practices across projects and enables AI coding assistants to follow your organization's guidelines automatically.

Engineering Rules

Guidelines for code quality, security, and performance.

Tech Standards

Standardized tech stacks (e.g., "Python + FastAPI").

MCP Server

Integration with Claude Code, Cursor, and more.

CLI Tool

Sync rules and validate compliance locally.

Prerequisites

  • Web Access: Convext web interface (local or deployed instance)
  • Node.js: Version 18 or higher (for CLI tool)
  • Git: For repository management
  • API Access: You'll need to create an API token

Step 1: Access Convext

Local Development

# Start the application
cd convext
bin/dev

# Access at http://localhost:3000

Production Instance

Access your deployed Convext instance (e.g., https://your-org.convext.app)

Step 2: Understand Organizations and Workspaces

When you first log in with GitHub OAuth, Convext automatically creates:

  • Personal Workspace: Your default organization for personal projects
  • Organization Workspaces: If you're part of GitHub organizations, those may be imported

Key Concepts

  • Organizations: Top-level containers for teams, rules, and standards
  • Projects: Individual codebases/repositories registered with Convext
  • RuleSets: Collections of rules and standards that can be assigned to projects
  • Marketplace: Public rulesets you can browse and adopt

Step 3: Create Your First API Token

API tokens are required for CLI tool authentication, MCP server integration, and API access.

Creating a Token

  1. Navigate to Settings → API Tokens
  2. Click "New Token"
  3. Enter a description (e.g., "CLI Access" or "Claude Code Integration")
  4. Click Create
  5. IMPORTANT: Copy the token immediately - it's only shown once!
Example Token: cc_live_abc123xyz789...

Secure Storage

# Option 1: Environment variable (recommended for CLI)
export CONVEXT_TOKEN="cc_live_abc123xyz789..."

# Add to your shell profile (~/.zshrc or ~/.bashrc)
echo 'export CONVEXT_TOKEN="cc_live_abc123xyz789..."' >> ~/.zshrc

# Option 2: CLI config (stored in ~/.convext/config.json)
convext config --token cc_live_abc123xyz789...

Step 4: Install the CLI Tool

The convext CLI tool is the bridge between your local development environment and the Convext platform.

Installation

# Install globally via npm
npm install -g @convext/cli

# Verify installation
convext --version

Authentication

If you haven't set the environment variable, you can configure the CLI directly:

convext config --token cc_live_abc123...

Step 5: Register Your First Project

Now, let's connect a local project to Convext.

  1. Navigate to your project's root directory in your terminal
  2. Run the initialization command:
cd ~/projects/my-awesome-app
convext init

This will:

  • Register the project with the Convext server
  • Create a .convext.json file linking the project ID
  • Prompt you to select an Organization (if you belong to multiple)

Commit the .convext.json file to your repository. It identifies the project for all team members.

Step 6: Browse and Assign RuleSets

By default, a new project has no rules. You need to assign RuleSets.

  1. Go to the Convext web interface
  2. Navigate to Projects and select your newly registered project
  3. Click "Manage RuleSets"
  4. Browse available RuleSets (from your Organization or the Marketplace)
  5. Click "Assign" on relevant RuleSets (e.g., "Rails Best Practices", "Security Baseline")

Tip: You can assign multiple RuleSets to a single project. Convext merges them intelligently.

Step 7: Sync Rules to Your Project

Back in your terminal, pull the assigned rules down to your local environment.

convext sync

This command:

  • Fetches all assigned rules and standards
  • Generates/Updates CLAUDE.md (for Claude Code)
  • Generates/Updates .cursorrules (for Cursor)
  • Generates/Updates .github/copilot-instructions.md (for Copilot)

Step 8: Verify the Setup

Check if your project complies with the new rules.

convext check

This will scan your codebase against the active rules and report any violations (errors or warnings).

Step 9: Integrate with Your IDE

Now that the configuration files are generated, your AI assistant is ready to use them.

  • Claude Code: Automatically detects CLAUDE.md. Just start using it!
  • Cursor: Automatically detects .cursorrules.
  • GitHub Copilot: Automatically detects .github/copilot-instructions.md (if enabled in your repo settings).

See the IDE Integration Guide for more details.

Step 10: Team Collaboration

To onboard your team:

  1. Ask them to install the CLI: npm install -g @convext/cli
  2. Have them generate their own API Token
  3. They clone the repo and run convext sync

Everyone will now be working with the exact same rules and standards.

Next Steps

CLI Reference

Master the command line interface.

Admin Guide

Learn to create rules and standards.

Troubleshooting

"Project not found" error

Ensure you are in the correct directory and that .convext.json exists and contains a valid project_id.

"Unauthorized" error

Check your API token. Run convext whoami to verify your identity.

Rules not updating

Run convext sync --force to overwrite local configuration files.

All Documentation CLI Guide