# How to Use the CommonGrants CLI Tool for Protocol Development

> Learn to use the CommonGrants CLI tool for protocol development. Initialize projects, compile TypeSpec to OpenAPI, preview specs, and validate standards with `cg`.

- Repository: [U.S. Department of Health & Human Services/simpler-grants-protocol](https://github.com/hhs/simpler-grants-protocol)
- Tags: how-to-guide
- Published: 2026-03-03

---

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

```bash

# 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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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.

```bash

# 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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/tspconfig.yaml).

```bash

# 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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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.

```bash

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

cg preview openapi.yaml

```

Located in [`lib/cli/src/commands/preview/preview.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/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.

```bash

# 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`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/cli/src/commands/check/check.ts) loads the appropriate base OpenAPI file from `lib/cli/lib/openapi/` (containing [`openapi.0.1.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/openapi.0.1.0.yaml), [`openapi.0.2.0.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/init.ts), [`compile.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/openapi.yaml). The CLI automatically uses the project's [`tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/openapi.0.2.0.yaml)) and compares it against your provided spec file. Implemented in [`lib/cli/src/commands/check/check.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/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.