# CommonGrants CLI Commands: Complete Developer Workflow Guide

> Explore CommonGrants CLI commands init compile preview check to scaffold projects compile TypeSpec to OpenAPI preview specs and validate implementations Unlock a streamlined developer workflow 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`) provides four core commands—`init`, `compile`, `preview`, and `check`—that enable developers to scaffold projects, compile TypeSpec to OpenAPI, preview specifications, and validate implementations against the Common Grants protocol.**

The CommonGrants CLI is the official command-line tool for the `hhs/simpler-grants-protocol` repository, built with the **commander** library to streamline the entire developer workflow. These CommonGrants CLI commands allow you to bootstrap new grant API projects, transform TypeSpec definitions into OpenAPI documents, and ensure compliance with the Common Grants protocol through integrated validation tools.

## Core CommonGrants CLI Commands

The CLI entry point at [`/lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/index.ts) registers all commands using the **commander** library. Each command is implemented in its own module under `/lib/cli/src/commands/`.

### `cg init`: Initialize New Projects

The `init` command creates a new Common Grants project from a starter template. Implemented in [`/lib/cli/src/commands/init/init.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/init/init.ts), it supports three modes:

- **Interactive mode**: Prompts you to select a template
- **List mode**: Displays available templates with `--list`
- **Direct specification**: Uses `--template <name>` to skip prompts

### `cg compile`: Convert TypeSpec to OpenAPI

Located at [`/lib/cli/src/commands/compile/compile.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/compile/compile.ts), the `compile` command transforms TypeSpec (`.tsp`) files into OpenAPI documents. It utilizes the project's [`tspconfig.yaml`](https://github.com/hhs/simpler-grants-protocol/blob/main/tspconfig.yaml) to determine compilation settings and output formats.

### `cg preview`: Local OpenAPI Preview

The `preview` command, found in [`/lib/cli/src/commands/preview/preview.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/preview/preview.ts), opens a local Swagger UI instance to visualize your API specification. It accepts both YAML and JSON OpenAPI files for immediate browser-based feedback.

### `cg check`: Validate Specifications and Live APIs

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), the `check` command provides two validation sub-commands:

**`cg check spec <specPath>`**

Validates an OpenAPI specification against the bundled Common Grants base protocol. Supports custom base specifications via `--base <path>` or specific protocol versions with `--protocol-version <version>`.

**`cg check api <apiUrl> <specPath>`**

Validates a running API implementation against its OpenAPI or TypeSpec definition. Supports various HTTP clients, authentication methods, and output formats including JSON reports.

## Command Usage Examples

Initialize a new project interactively:

```bash
cg init

```

List available starter templates:

```bash
cg init --list

```

Initialize with a specific template:

```bash
cg init --template custom-api

```

Compile TypeSpec to OpenAPI:

```bash
cg compile my-api.tsp

```

Preview the generated OpenAPI file locally:

```bash
cg preview openapi.yaml
cg preview spec.json

```

Validate a specification against the Common Grants protocol:

```bash

# Use bundled base spec

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 ./base.yaml

```

Validate a live API implementation:

```bash
cg check api https://api.mygrant.org spec.yaml \
    --client fetch \
    --report json \
    --auth bearer:mytoken

```

Display built-in help:

```bash
cg --help
cg help check

```

## Summary

- The **`cg init`** command scaffolds new projects from starter templates via [`/lib/cli/src/commands/init/init.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/init/init.ts).
- The **`cg compile`** command transforms TypeSpec files into OpenAPI documents using [`/lib/cli/src/commands/compile/compile.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/compile/compile.ts).
- The **`cg preview`** command launches local Swagger UI previews for YAML or JSON specs via [`/lib/cli/src/commands/preview/preview.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/preview/preview.ts).
- The **`cg check`** command validates both static specifications and live API implementations via [`/lib/cli/src/commands/check/check.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/check/check.ts).
- All commands are registered in [`/lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/index.ts) using the **commander** library, with user-facing documentation available in [`/lib/cli/README.md`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/README.md).

## Frequently Asked Questions

### How do I list available commands and options in the CommonGrants CLI?

Run `cg --help` to display all top-level commands, or `cg help [command]` for detailed information about a specific command. This help system is provided automatically by the **commander** library as configured in [`/lib/cli/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/index.ts).

### Can I validate my API against a specific version of the Common Grants protocol?

Yes. Use `cg check spec <specPath> --protocol-version 0.2.0` to validate against a specific protocol version, or specify a custom base specification with `--base ./custom-base.yaml`. The validation logic resides in [`/lib/cli/src/commands/check/check.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/check/check.ts).

### What file types does the `cg preview` command support?

The `cg preview` command accepts both **YAML** and **JSON** OpenAPI specifications. You can preview files with `cg preview openapi.yaml` or `cg preview api-spec.json`, as implemented in [`/lib/cli/src/commands/preview/preview.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/preview/preview.ts).

### How does the `cg check api` command authenticate with protected endpoints?

The `cg check api` command supports authentication via the `--auth` flag, accepting formats like `bearer:TOKEN` or `basic:user:pass`. It also allows you to specify the HTTP client (such as `fetch` or `undici`) using the `--client` option. See [`/lib/cli/src/commands/check/check.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main//lib/cli/src/commands/check/check.ts) for implementation details.