CLI Tool

The Constellation CLI is a powerful command-line utility that parses source code locally, extracts source code metadata, and uploads the data to the Constellation service for team-wide code intelligence sharing.

Overview

The Constellation CLI tool is designed with privacy and security in mind. It parses your source code locally and only transmits serialized code metadata to the Constellation service. Your proprietary source code never leaves your environment, only structural metadata is transmitted. This ensures complete privacy while enabling powerful code intelligence features for your entire team.

How It Works:

1. Local Parsing: The CLI parses source code on your system and derives metadata
2. Metadata Serialization: Source code metadata is serialized and compressed (source text is removed)
3. Data Streaming: Compressed metadata is streamed efficiently to the Constellation service
4. Index Enrichment: If language servers are available locally, the CLI queries them for additional type information and cross-references, uploading the results to refine the intelligence graph
5. Server-Side Intelligence: The service extracts and derives code intelligence from the metadata
6. Knowledge Graph: Composed code intelligence is indexed in your team's shared code knowledge graph

Installation

Install the Constellation CLI utility globally using NPM:

npm install -g @constellationdev/cli@latest

The CLI can be utilized with either command alias: constellation or the shorter alias const. Examples in this documentation use const, but constellation accepts the same subcommands, flags, and arguments.

Features:

• Privacy-First: Parses code locally, only sends metadata (source code never transmitted)
• Incremental Indexing: Intelligently processes only changed files since last index
• Full Indexing: Optionally perform complete project re-index as necessary
• Index Enrichment: Automatically queries local language servers to enhance the code intelligence graph with additional type information, call hierarchies, and cross-references
• Git Integration: Validates branch and working tree state to prevent index pollution
• Data Streaming: Efficient streaming protocol handles codebases of any size
• Progress Tracking: Shows real-time progress during processing
• Fault Tolerance: Continues processing even if individual files fail

Usage:

# Perform smart indexing (incremental by default)
const index

# Force a full project re-index
const index --full

# Explicitly request incremental update
const index --incremental

# Skip index enrichment for this run
const index --no-enrich

# Skip git validation (testing/troubleshooting only - not recommended)
const index --dirty

Environment Variables

Variable	Description
CONSTELLATION_ACCESS_KEY	Required. Access key for API authentication (format: ak: followed by 32 hex characters). Set via const auth or manually.
CONSTELLATION_ASCII_MODE	Set to 1 to force ASCII-only terminal output (no Unicode symbols). Useful for terminals that don't support Unicode.
CONSTELLATION_ERROR_REPORTING	Set to false to disable automatic error reporting to the Constellation service.
CONSTELLATION_AST_WAIT_MAX_MS	Optional override (in milliseconds) for the maximum time the CLI waits for the server to finish ingestion after upload. By default, the cap scales with project size (15 min for small repos, 30 min at ≥10k files, 45 min at ≥50k files). Use a higher value for very large or slow servers; invalid values are ignored with a warning.

Requirements

• Node.js: Version 20 or higher
• npm: Version 10 or higher
• Git: Must be installed and available in PATH
• Repository: Must be run from the root directory of a Git repository
• Configuration: Requires constellation.json (can be created by init command)