kuu

English | 日本語

A language-agnostic specification for CLI argument definitions, with a conformance suite.

The core of kuu is not a binary in any particular language — it is the spec + API contract + conformance fixtures (a language-neutral test-data corpus). Each language gets a native implementation of this core; kuu.mbt is the reference implementation, and kuu-cli is a standalone CLI frontend.

• Want to try the CLI → kuu-cli
• Embedding into a MoonBit project → kuu.mbt (reference implementation)
• Reading the spec / writing a new implementation → this repo

A CLI is defined as a JSON document (the wire form), and any conforming implementation parses argv against it with identical observable behavior:

{
  "options": [
    {"name": "port", "type": "number", "long": true, "short": "p", "env": "PORT", "default": 8080},
    {"name": "verbose", "type": "flag", "long": true}
  ],
  "commands": [
    {"type": "command", "name": "serve", "positionals": [{"name": "dir", "type": "string"}]}
  ]
}

Definitions cover long/short options, subcommands, positionals, repetition, value sources (CLI / env / config files / tty), constraints, aliases, completion and help — all specified declaratively, all pinned by conformance fixtures.

Add "$schema": "https://raw.githubusercontent.com/kawaz/kuu/main/schema/wire.schema.json" to your def.json to get editor completion / validation in JSON-Schema-aware editors (VS Code etc.).

This repo itself is a spec, not a runtime — the fastest tour is to read one fixture and run the schema lints.

git clone https://github.com/kawaz/kuu
cd kuu

# Validate the descriptor registry against the descriptor schema + semantic invariants.
just lint-descriptors

# Validate that docs/REFERENCE.md covers every vocabulary key in the schemas.
just lint-reference

# Read one conformance fixture — a definition + argv + expected outcome.
cat fixtures/absent/no-source-and-default.json

Each fixture in fixtures/ is self-explanatory: definition is the wire form, cases[].args is the argv, and cases[].expect is what every conforming implementation must produce. To exercise an implementation against this corpus, use kuu.mbt.

External-facing (spec, contract, corpus):

Internal (maintainer working files — kept in-repo for transparency, not part of the public spec surface):

Most in-repo documentation is currently written in Japanese while the spec is under heavy iteration; the spec itself is defined by the documents and fixtures above.

Draft. The spec is largely settled through co-design with the reference implementation, and breaking changes are still allowed across the board. Version 1.0.0 will be published once all conformance profiles are green on the reference implementation.

MIT © Yoshiaki Kawazu