How to Use the CommonGrants CLI Tool for Protocol Development

The CommonGrants CLI (cg) is the official command-line interface for the CommonGrants protocol, providing commands to initialize projects, compile TypeSpec to OpenAPI, preview specifications locally, and validate against protocol standards.

The CommonGrants CLI tool simplifies working with the CommonGrants protocol in the hhs/simpler-grants-protocol repository. It wraps the TypeSpec compiler with ergonomic helper commands that handle project scaffolding, OpenAPI generation, and protocol compliance checking without requiring deep TypeScript expertise.

Installation and Setup

Install the CLI globally to access the cg command from any terminal, or use npx for one-off executions.

# Global installation adds `cg` to your PATH

npm install -g @common-grants/cli

# Alternative: run without installing

npx @common-grants/cli --help

The CLI entry point is defined in lib/cli/src/index.ts, which sets up the commander program, registers all sub-commands, and configures global error handling via handleCommandError.

Core Commands Overview

The CommonGrants CLI provides four primary commands that map to distinct phases of the protocol development lifecycle.

Initialize a New Project (cg init)

The init command bootstraps a new CommonGrants project from curated templates, generating the necessary TypeSpec configuration and starter files.

# Interactive wizard for project setup

cg init

# List available templates

cg init --list

# Initialize with a specific template (e.g., fast-api)

cg init --template fast-api

Implementation resides in lib/cli/src/commands/init/init.ts. The command parses options, validates them with Zod schemas, and delegates to DefaultInitService.init() to handle file system operations and template rendering.

Compile TypeSpec Files (cg compile)

The compile command transforms TypeSpec (.tsp) files into OpenAPI specifications, invoking the TypeSpec compiler with the project's tspconfig.yaml.

# Compile to openapi.yaml (default)

cg compile src/main.tsp

# Compile to JSON format

cg compile src/main.tsp --output openapi.json

The command implementation in lib/cli/src/commands/compile/compile.ts forwards requests to CompileService, which runs tsp compile and manages output paths.

Preview OpenAPI Specifications (cg preview)

The preview command launches a local Express server serving Swagger UI, allowing real-time exploration of generated OpenAPI documents.

# Start preview server on http://localhost:3000

cg preview openapi.yaml

Located in lib/cli/src/commands/preview/preview.ts, this command uses PreviewService to spin up the server with auto-reload capabilities when the specification file changes.

Validate Specifications (cg check)

The check command validates an OpenAPI specification against the official CommonGrants protocol, identifying missing routes, extra routes, or schema mismatches.

# Validate against latest bundled protocol version

cg check spec openapi.yaml

# Validate against specific protocol version

cg check spec openapi.yaml --protocol-version 0.2.0

# Validate against custom base specification

cg check spec openapi.yaml --base ./my-base-spec.yaml

Implementation in lib/cli/src/commands/check/check.ts loads the appropriate base OpenAPI file from lib/cli/lib/openapi/ (containing openapi.0.1.0.yaml, openapi.0.2.0.yaml, etc.) and delegates to CheckService for compatibility analysis.

CLI Architecture and Implementation

The CommonGrants CLI follows a layered architecture that separates command parsing from business logic.

Command Layer: The entry point in lib/cli/src/index.ts configures the commander program and registers sub-commands. Each command file in lib/cli/src/commands/<name>/ (e.g., init.ts, compile.ts) handles argument parsing and Zod validation.

Service Layer: Pure TypeScript classes in *-service.ts files encapsulate core operations. For example, CompileService manages TypeSpec compiler invocation, while CheckService handles OpenAPI comparison logic. This pattern keeps commands thin and testable.

Bundled Resources: The CLI ships with pre-compiled OpenAPI specifications for each protocol version stored in lib/cli/lib/openapi/. The check command automatically selects the correct base file based on the --protocol-version flag, defaulting to the latest bundled version.

Error Handling: Centralized error management in lib/cli/src/utils/error.ts ensures consistent formatting and exit codes across all commands.

Typical Development Workflow

A standard protocol development workflow using the CommonGrants CLI tool involves four phases:

1. Bootstrap: Run cg init to scaffold a new project directory with main.tsp, tspconfig.yaml, and template-specific boilerplate.

2. Define: Edit the TypeSpec files to describe grant API routes, models, and custom fields using the @common-grants/core library.

3. Compile: Execute cg compile main.tsp to generate openapi.yaml. The CLI automatically uses the project's tspconfig.yaml for compiler options.

4. Validate: Run cg check spec openapi.yaml to verify compliance against the bundled CommonGrants protocol specification. Address any reported mismatches before deployment.

5. Preview: Use cg preview openapi.yaml to launch a local Swagger UI instance for manual testing and stakeholder review.

Summary

• The CommonGrants CLI (cg) provides a command-line interface for the hhs/simpler-grants-protocol repository, wrapping TypeSpec compiler functionality with ergonomic helper commands.
• Installation is available via npm install -g @common-grants/cli or npx for temporary usage.
• Core commands include init for project scaffolding, compile for TypeSpec-to-OpenAPI conversion, preview for local Swagger UI hosting, and check for protocol compliance validation.
• Architecture follows a command-service pattern with commander.js for parsing, Zod for validation, and dedicated service classes for business logic in lib/cli/src/commands/.
• Bundled OpenAPI specifications in lib/cli/lib/openapi/ enable offline validation against specific protocol versions without external dependencies.

Frequently Asked Questions

How do I install the CommonGrants CLI tool globally?

Install the package using npm with the global flag to add the cg command to your system PATH. Run npm install -g @common-grants/cli in your terminal. After installation, verify the installation by running cg --help to see available commands and options.

What is the difference between cg compile and running TypeSpec directly?

The cg compile command in lib/cli/src/commands/compile/compile.ts is a thin wrapper around the TypeSpec compiler (tsp compile) that automatically manages project configuration and output paths. It reads your tspconfig.yaml and delegates to CompileService, providing consistent error handling and formatted output without requiring you to remember TypeSpec-specific flags.

How does the cg check command validate my OpenAPI specification?

The cg check command loads a bundled base OpenAPI specification from lib/cli/lib/openapi/ (such as openapi.0.2.0.yaml) and compares it against your provided spec file. Implemented in lib/cli/src/commands/check/check.ts and CheckService, it identifies missing routes, extra routes, and schema mismatches against the CommonGrants protocol standards. You can specify a particular protocol version using the --protocol-version flag.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}