Configuration

Setting up Constellation requires two steps: authenticating and configuring your project settings.

Authentication

The Constellation CLI and MCP server both require a valid access key to authenticate with the Constellation service.

Setting Up Authentication

The access key must be set as the CONSTELLATION_ACCESS_KEY environment variable. The easiest way to configure this is using the CLI tool auth command:

constellation auth

This command will open a browser to authenticate you, retrieve your preferred access key, and automatically set the environment variable on your system (Windows, macOS, and Linux).

Alternatively, you can manually set the environment variable:

macOS/Linux:

Add the following line to your shell profile "run commands" file (~/.bashrc or ~/.zshrc for example):

export CONSTELLATION_ACCESS_KEY="your-access-key-here"

Windows (PowerShell):

$env:CONSTELLATION_ACCESS_KEY="your-access-key-here"

Environment Variables

The following environment variables configure CLI behavior:

Variable	Required	Description
CONSTELLATION_ACCESS_KEY	Yes	Access key for API authentication. Format: ak: followed by 32 hex characters (e.g., ak:00000000000040008000000000000002). Set via constellation auth or manually in your shell profile.
CONSTELLATION_ASCII_MODE	No	Set to 1 to force ASCII-only terminal output. Replaces Unicode symbols (✔, ✗, ⚠, ℹ, ⚡) with ASCII equivalents ([OK], [ERR], [WARN], [INFO], [!]). Useful for terminals or CI systems that don't render Unicode correctly.
CONSTELLATION_ERROR_REPORTING	No	Set to false to disable automatic error reporting to the Constellation service. When enabled (default), the CLI may send anonymized error and warning data to help improve the service.

Project Configuration

The CLI and MCP server both use a constellation.json file in your project repository root folder for project-specific configuration. You can create this file manually or use the init command to generate it interactively:

constellation init

This will guide you through creating a properly configured constellation.json file.

Example Configuration File

{
  "projectId": "proj:00000000000000000000000000000000",
  "branch": "main",
  "languages": {
    "typescript": {
      "fileExtensions": [".ts", ".tsx"]
    },
    "javascript": {
      "fileExtensions": [".js", ".jsx"]
    }
  },
  "exclude": ["tests/**"]
}

Configuration Fields

• projectId (required): Unique project identifier (from your Constellation web dashboard).
• branch (required): Git branch to track and index (e.g., "main", "develop").
• languages (required): Language configuration mapping language names to their file extensions. At least one language must be configured. See Per-Language Configuration for additional options.
• exclude (optional): Array of glob patterns for paths or files to exclude from indexing (e.g., ["node_modules/**", "dist/**", "*.test.ts"]).
• lspEnrichment (optional): Set to false to disable index enrichment for all languages. Defaults to true (enrichment runs automatically when language servers are available). See Index Enrichment.

Per-Language Configuration

Each language entry under languages supports the following fields:

• fileExtensions (required): Array of file extensions to include (e.g., [".ts", ".tsx"]). Each must start with a dot.

• lspEnrichment (optional): Set to false to disable index enrichment for this specific language. Overrides the default (enabled) but cannot override a root-level lspEnrichment: false.

• lsp (optional): Custom language server configuration. When omitted, the CLI uses its built-in server registry for auto-detection. When provided, overrides the default server for this language.

  "lsp": {
    "command": "my-custom-language-server",
    "args": ["--stdio"]
  }

Example with enrichment options:

{
  "projectId": "proj:00000000000000000000000000000000",
  "branch": "main",
  "languages": {
    "typescript": {
      "fileExtensions": [".ts", ".tsx"]
    },
    "python": {
      "fileExtensions": [".py"],
      "lspEnrichment": false
    }
  }
}

In this example, TypeScript files are enriched automatically (using the auto-detected typescript-language-server), while Python enrichment is disabled.

Index Enrichment

Index enrichment is an optional feature that enhances the code intelligence graph by querying language servers locally after indexing. It provides additional type information, call hierarchies, and cross-reference data that improve the accuracy of code intelligence queries.

Enrichment runs automatically when:

1. A compatible language server is detected on your system (installed globally or in ~/.constellation/lsp-servers/).
2. The language is not opted out via lspEnrichment: false.
3. The --no-enrich CLI flag is not set.

Precedence rules:

• Root-level lspEnrichment: false disables enrichment for all languages.
• Per-language lspEnrichment: false disables enrichment for that language only.
• Both default to true when omitted — enrichment is enabled by default.
• A per-language lsp config object overrides the built-in server auto-detection for that language.

No configuration is required for supported languages. The CLI auto-detects installed language servers from its built-in registry. See Index Enrichment in the commands reference for the list of supported languages.