Skip to main content

Commands

init​

Initialize a new Constellation project configuration in your repository.

Description: This command sets up your project for Constellation by creating a constellation.json configuration file. It must be run from from the root directory of a project's Git repository.

Features:

  • Detects Git repository and validates it's properly initialized.
  • Prompts for project configuration settings.
  • Automatically detects git repo remote origin URL to suggest a namespace.
  • Stages the created constellation.json file in Git.

Usage:

constellation init

Interactive Prompts:

  1. Project Namespace: A unique identifier for your project (defaults to remote repository name).
  2. Branch to Index: Select which Git branch to track and index.
  3. Languages: Multi-select the programming languages used in your project.

Currently Supported Languages:

  • JavaScript
  • TypeScript

Additional language support is under development.

Requirements:

  • Must be run from from the root directory of a Git repository.
  • Git must be installed and available in PATH.
  • Creates constellation.json in the current directory.

auth​

Configure authentication for the Constellation CLI.

Description: Sets up authentication credentials for connecting to your team's Constellation service. Stores provided Constellation Key in user environment variables.

Usage:

constellation auth

Interactive Prompts:

  1. Constellation Access Key: Prompts for user/developer Constellation Access Key for authentication to Constellation service.

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).

    ⚠️ 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.

What Gets Indexed:

  • All files matching the language extensions configured in constellation.json.
  • Only files tracked by Git (respects .gitignore).
  • Processes files from the configured branch.

Performance:

  • Processes files individually to optimize memory usage.
  • Shows progress with each file processed.
  • Handles large codebases efficiently.
  • Continues processing even if individual files fail to parse.

Error Handling:

  • Validates Git repository state before indexing.
  • Reports parsing errors but continues processing.
  • Provides detailed error messages for troubleshooting.
  • Returns non-zero exit code on critical failures.