usage-spec

Monorepo for generating usage spec from CLI framework metadata.

Packages

JavaScript / TypeScript

Package	Description
@usage-spec/core	Shared Spec types, KDL/JSON rendering via @bgotink/kdl
@usage-spec/commander	Commander.js integration
@usage-spec/yargs	yargs integration
@usage-spec/oclif	oclif integration

Python

Package	PyPI	Description
usage-spec	usage-spec	Core Spec types and KDL/JSON rendering (Python port of @usage-spec/core)
usage-spec-argparse	usage-spec-argparse	argparse integration
usage-spec-click	usage-spec-click	Click integration
usage-spec-typer	usage-spec-typer	Typer integration (built on top of usage-spec-click)

Usage

JavaScript / TypeScript

Each adapter package provides the same API surface:

import { generate, generateKDL, generateJSON, convertRoot } from "@usage-spec/<adapter>";

// Generate KDL spec
const kdl = generate(frameworkInstance);

// Generate JSON spec
const json = generateJSON(frameworkInstance);

// Get Spec object for custom processing
const spec = convertRoot(frameworkInstance);

Python

Each Python adapter package provides the same API surface:

from <adapter>_usage import generate, generate_kdl, generate_json, convert_root

# Generate KDL spec (default)
kdl = generate(framework_instance)

# Generate KDL spec explicitly
kdl = generate_kdl(framework_instance)

# Generate JSON spec
json_str = generate_json(framework_instance)

# Get Spec object for custom processing
spec = convert_root(framework_instance)

For example, with Click:

import click
from click_usage import generate

@click.group()
def cli():
    pass

# Print KDL spec
print(generate(cli, bin_name="mycli"))

Pipe KDL output to the usage CLI for completions, docs, and man pages:

mycli --usage-spec | usage generate completion bash

Development

JavaScript / TypeScript

aube install -r       # Install dependencies
aube run build -r     # Build all packages
aube run test -r      # Run all tests

Python

uv sync               # Install dependencies
uv run pytest         # Run all tests

License

MIT