CommonGrants CLI Commands: Complete Developer Workflow Guide

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 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, 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, the compile command transforms TypeSpec (.tsp) files into OpenAPI documents. It utilizes the project's 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, 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, 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:

cg init

List available starter templates:

cg init --list

Initialize with a specific template:

cg init --template custom-api

Compile TypeSpec to OpenAPI:

cg compile my-api.tsp

Preview the generated OpenAPI file locally:

cg preview openapi.yaml
cg preview spec.json

Validate a specification against the Common Grants protocol:

# 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:

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

Display built-in help:

cg --help
cg help check

Summary

• The cg init command scaffolds new projects from starter templates via /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.
• The cg preview command launches local Swagger UI previews for YAML or JSON specs via /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.
• All commands are registered in /lib/cli/src/index.ts using the commander library, with user-facing documentation available in /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.

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.

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.

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 for implementation details.

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