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)

Kotlin / JVM

Published to GitHub Packages.

Package	Maven coordinates	Description
usage-spec-kotlin	dev.usage-spec:usage-spec-kotlin	Core Spec types, KDL/JSON rendering via kdl4j and kotlinx-serialization
jcommander-usage	dev.usage-spec:jcommander-usage	JCommander integration
picocli-usage	dev.usage-spec:picocli-usage	picocli integration
clikt-usage	dev.usage-spec:clikt-usage	Clikt integration

Go

Package	Go module	Description
usage-spec-go	github.com/gaojunran/usage-integrations/packages/usage-spec-go	Core Spec types, KDL/JSON rendering via calico32/kdl-go
cobra-usage	github.com/gaojunran/usage-integrations/packages/cobra-usage	Cobra integration
kong-usage	github.com/gaojunran/usage-integrations/packages/kong-usage	Kong integration
urfavecli-usage	github.com/gaojunran/usage-integrations/packages/urfavecli-usage	urfave/cli v2 integration

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"))

Kotlin / JVM

Add the GitHub Packages repository and dependency:

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/gaojunran/usage-integrations")
        credentials {
            username = findProperty("githubUsername") as String? ?: System.getenv("GITHUB_USERNAME")
            password = findProperty("githubToken") as String? ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation("dev.usage-spec:clikt-usage:1.1.0")
}

Each adapter provides the same API surface:

import clikt_usage.generate
import clikt_usage.generateJSON
import clikt_usage.convertRoot

// Generate KDL spec
val kdl = generate(command)

// Generate JSON spec
val json = generateJSON(command)

// Get Spec object for custom processing
val spec = convertRoot(command)

Go

Each adapter package provides the same API surface:

import (
    cobrausage "github.com/gaojunran/usage-integrations/packages/cobra-usage"
)

// Generate KDL spec
kdl := cobrausage.GenerateKDL(cmd)

// Generate JSON spec
json := cobrausage.GenerateJSON(cmd)

// Get Spec object for custom processing
spec := cobrausage.ConvertRoot(cmd)

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

Kotlin / JVM

./gradlew test        # Run all tests
./gradlew publishToMavenLocal   # Publish to local Maven repo

Go

cd packages/usage-spec-go && go test ./...
cd packages/cobra-usage && go test ./...
cd packages/kong-usage && go test ./...
cd packages/urfavecli-usage && go test ./...

License

MIT