Skip to main content

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. Server-Side Intelligence: The service extracts and derives code intelligence from the metadata
  5. 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

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
  • 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)
constellation index

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

# Explicitly request incremental update
constellation index --incremental

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

Requirements​

  • Node.js: Version 18 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)