Commands

init

Initialize a new Constellation project configuration in your repository.

Description: Sets up your project for Constellation by creating a constellation.json configuration file, configuring MCP servers for AI coding assistants, and optionally setting up a CI/CD pipeline for automatic indexing. Supports idempotent re-initialization — if constellation.json already exists, current values are used as defaults.

Usage:

constellation init

Options:

• --skip-mcp: Skip the MCP server configuration step for AI coding tools.
• --skip-ci: Skip the CI/CD pipeline configuration step.

Interactive Prompts:

1. Project ID: Your Constellation project identifier (created in the web app).
2. Branch to Index: Select which Git branch to track and index (defaults to current branch).
3. Languages: Multi-select the programming languages used in your project.
4. MCP Configuration: Choose which AI coding assistants to configure.
5. CI/CD Pipeline: Set up GitHub Actions or GitLab CI for automatic indexing on push.

What It Configures:

• constellation.json — Project configuration with branch, languages, and project ID. Staged in Git automatically.
• MCP servers — Adds the Constellation MCP server to your selected AI coding tool configurations (project-level or global, depending on the tool).
• AI hooks — Injects Constellation awareness prompts into tools that support lifecycle hooks (session start, subagent spawn, context compaction).
• CI/CD pipeline — Creates a GitHub Actions workflow or GitLab CI job for automatic indexing. Detects your platform automatically.

Requirements:

• Must be run from a Git repository.
• Git must be installed and available in PATH.

auth

Configure authentication for the Constellation CLI.

Description: Sets up authentication credentials for connecting to your team's Constellation service. By default, opens your browser to the Constellation web app where you sign in and select (or create) an access key. The key is automatically sent back to the CLI via a secure localhost callback — no copy-pasting required.

For headless or CI-adjacent environments where a browser isn't available, use the --manual flag to paste your access key directly.

Usage:

Browser-based flow (default):

constellation auth

Options:

• --manual: Use the manual access key entry flow instead of browser-based authentication. Prompts you to paste an access key directly with format validation and retry support.

Browser Flow:

1. Opens your default browser to the Constellation web app.
2. You sign in (if not already) and select or create an access key.
3. The key is securely sent back to the CLI.
4. CLI stores the key in your user environment variables.

If the browser fails to open automatically, the CLI prints the URL for you to open manually.

Manual Flow (--manual):

1. Prompts for your access key (hidden input).
2. Validates the key format.
3. Allows up to 3 retry attempts for invalid formats.
4. Stores the key in your user environment variables.

Notes:

• The auth command is blocked in CI/CD environments. Configure CONSTELLATION_ACCESS_KEY directly in your pipeline secrets instead.
• If you already have a stored key, you'll be prompted to confirm replacement before proceeding.

index

Create or update the Constellation data indices for your project.

This is the foundational command that parses your source code, generates source code metadata, and uploads it to the Constellation service. It supports both full and incremental indexing.

Options:

• --full: Forces a complete re-index of all project files.

• --incremental: Explicitly requests incremental indexing (default behavior when previous index exists).

• --dirty: Skips git validation checks (branch and working tree status).

• --no-enrich: Skips index enrichment even when language servers are available.

  ⚠️ WARNING: The --dirty flag is intended for testing and troubleshooting only. It bypasses important git validation checks that prevent index pollution from uncommitted changes or branch mismatches. Not recommended for production use as it may result in an inconsistent or polluted code index.

Process Flow:

1. Git Branch Validation: Ensures current branch matches configuration.
2. Repository Synchronization: Pulls latest changes from remote.
3. Index Scope Determination: Decides between full or incremental index.
4. File Discovery: Scans project for files matching configured languages.
5. Metadata Generation: Parses each file and generates source code metadata.
6. Data Upload: Compresses and uploads metadata to service.
7. Index Enrichment (optional): If language servers are available, runs enrichment queries locally to enhance the code intelligence graph with additional type information, call hierarchies, and cross-reference data. Enrichment runs concurrently with data upload and never blocks the core indexing pipeline. See Index Enrichment for details.

CI/CD Behavior:

When running in a CI/CD environment (detected automatically via standard CI environment variables):

• Defaults to --full index unless --incremental is explicitly passed.
• The auth command is blocked — use the CONSTELLATION_ACCESS_KEY environment variable in your pipeline secrets instead.
• The ASCII banner and update checks are suppressed.

What Gets Indexed:

• All files matching the language extensions configured in constellation.json.
• Only files tracked by Git (respects .gitignore).
• Custom exclusion patterns defined in the exclude field of constellation.json.
• Processes files from the configured branch.

Index Enrichment

Index enrichment is an optional post-indexing step that enhances the code intelligence graph with additional type information, call hierarchies, and cross-reference data. It runs automatically when supported language servers are detected on your system.

How It Works:

1. After the core indexing pipeline uploads metadata, the CLI checks which indexed languages have a compatible language server available.
2. For each eligible language, a language server is started locally and queried for hover information, definitions, references, and call hierarchies.
3. The enrichment data is uploaded to the Constellation service where it refines and corrects relationships in the code intelligence graph.

Supported Languages:

Language	Language Server	Auto-Detected
TypeScript	typescript-language-server	Yes
JavaScript	typescript-language-server	Yes
Python	pyright-langserver	Yes

If a language server is not installed, enrichment is silently skipped for that language — the core index is unaffected.

Controlling Enrichment:

• Skip enrichment for a single run: Use --no-enrich flag.
• Disable enrichment for a specific language: Set lspEnrichment: false in the language config in constellation.json.
• Disable enrichment globally: Set lspEnrichment: false at the root of constellation.json.
• Custom language server: Override the default server with a lsp config block per language.

See Configuration for details on these settings.