clap_types

clap_types turns Rust CLIs into multi-language client libraries.

If your Rust tool is defined with clap, clap_types reflects its command tree and generates strongly-typed clients for TypeScript, Flow-annotated JavaScript, Python, Rust, and Kotlin/JVM. Those clients know how to build argv, optionally invoke the executable, and optionally describe or parse structured output contracts.

The goal is to make CLIs feel like real programmatic APIs without giving up why CLIs are great in the first place: they are easy to install, easy to sandbox, easy to call from agents and skills, and naturally cross-process.

Rust CLIs are often the best packaging format for local tools, but hand-written wrappers quickly become stringly typed drift:

callers guess which arguments are required;
enums and nested subcommands get duplicated by hand;
file paths, booleans, counters, and repeated values lose their shape;
stdout parsing is ad hoc and usually undocumented.

clap_types treats your clap::Command as the input IDL and explicit output contracts as the output IDL. It generates clients that can be checked, linted, and shipped with the same care as any other library.

That means callers get an idiomatic library instead of a pile of string concatenation. The generated code knows the right subcommand order, where global arguments belong, how varargs and repeated options expand, and which fields are required before anything is sent to the tool.

Status

This project is early and pre-1.0. The architecture is intentionally similar to clap_complete, clap_mangen, and clap-markdown: reflect a clap::Command, convert it into a language-neutral model, then render one or more target-language artifacts.

Supported backends:

TypeScript: dependency-free argv builders.
TypeScript + Zod: opt-in strict schemas and runtime validation.
TypeScript + Node: opt-in child_process command descriptors, execFile, and spawn helpers.
Flow: dependency-free JavaScript argv builders with Flow exact object types.
Flow + Zod / Node: the same opt-in validation and child_process helpers as the TypeScript backend.
Python 3.10+: dataclasses, argv builders, single-file modules, package layouts, and subprocess.run convenience.
Rust: dependency-free structs, enums, argv builders, and std::process helpers.
Kotlin/JVM: desktop-friendly data classes, enums, argv builders, and ProcessBuilder helpers.

Every backend can opt into generated output-contract metadata and dependency-free framing helpers with .output_contracts() or the hidden command's --output-contracts flag.

What You Get

Multi-language input clients from one Rust CLI definition.
Generated types for subcommands, globals, required args, enums, counters, booleans, repeated options, varargs, paths, numbers, and strings.
Optional standard-library invocation helpers for Node, Python, Rust, and Kotlin/JVM.
Runtime validation before invocation in opt-in modes such as TypeScript + Zod or Flow + Zod.
Optional output-contract metadata for JSON, JSON-lines, text, streaming, and interactive commands, with automatic parsing where the generated language can do that cleanly without extra dependencies.
A path toward typed success and error returns, so callers can know what to expect back instead of scraping stdout and exit codes by hand.
A hidden generate-binding command you can embed in your own CLI so the tool can generate clients for itself.
Generated-code tests in CI across Rust, Python 3.10-3.14, TypeScript and Flow on Node and Bun, and Kotlin/JVM.

Install

Add clap_types to the crate that defines your CLI:

[dependencies]
clap = { version = "4", features = ["derive"] }
clap_types = "0.1"

For now, while developing locally, use a path dependency:

[dependencies]
clap = { version = "4", features = ["derive"] }
clap_types = { path = "../clap_types" }

Quick Start

use clap::{Arg, ArgAction, Command};
use clap_types::{generate, Flow, Kotlin, Python, Rust, TypeScript};

fn build_cli() -> Command {
    Command::new("demo")
        .about("Example CLI")
        .arg(Arg::new("config").long("config").action(ArgAction::Set))
        .arg(Arg::new("verbose").short('v').action(ArgAction::Count))
}

let cmd = build_cli();
generate(TypeScript::new(), &cmd, "demo", &mut std::io::stdout())?;

let cmd = build_cli();
generate(TypeScript::new().zod(), &cmd, "demo", &mut std::io::stdout())?;

let cmd = build_cli();
generate(TypeScript::new().node(), &cmd, "demo", &mut std::io::stdout())?;

let cmd = build_cli();
generate(Flow::new().zod().node(), &cmd, "demo", &mut std::io::stdout())?;

let cmd = build_cli();
generate(
    Python::new()
        .module_name("demo_bindings")
        .namespace("Demo"),
    &cmd,
    "demo",
    &mut std::io::stdout(),
)?;

let cmd = build_cli();
generate(Rust::new(), &cmd, "demo", &mut std::io::stdout())?;

let cmd = build_cli();
generate(Kotlin::new(), &cmd, "demo", &mut std::io::stdout())?;
# Ok::<(), std::io::Error>(())

For file generation, use generate_to:

use clap::Command;
use clap_types::{generate_to, TypeScript};

let cmd = Command::new("demo");
let path = generate_to(TypeScript::new(), &cmd, "demo", "target/generated")?;
assert_eq!(path.file_name().unwrap(), "demo.ts");
# Ok::<(), std::io::Error>(())

Hidden subcommands and args are skipped by default. Use generate_to_with_options with ReflectOptions::all() to include them:

use clap::Command;
use clap_types::{generate_to_with_options, ReflectOptions, TypeScript};

let cmd = Command::new("demo");
let path = generate_to_with_options(
    TypeScript::new(),
    &cmd,
    "demo",
    "target/generated",
    ReflectOptions::all(),
)?;
# assert_eq!(path.file_name().unwrap(), "demo.ts");
# Ok::<(), std::io::Error>(())

Hidden Binding Command

Applications can expose every clap_types backend through a hidden clap subcommand. This makes bindings generation part of the tool itself, which is handy for build scripts, package publishing, and agent environments that install the CLI first and ask it to describe itself later.

use clap::{Arg, Command};
use clap_types::{BINDING_COMMAND_NAME, binding_command, generate_binding_from_matches};

fn build_cli() -> Command {
    Command::new("demo").subcommand(Command::new("run").arg(Arg::new("target").required(true)))
}

fn main() -> std::io::Result<()> {
    let matches = build_cli().subcommand(binding_command()).get_matches();

    if let Some((BINDING_COMMAND_NAME, binding_matches)) = matches.subcommand() {
        let cmd = build_cli();
        let path = generate_binding_from_matches(&cmd, "demo", binding_matches)?;
        eprintln!("generated {}", path.display());
        return Ok(());
    }

    Ok(())
}

The hidden command supports the current generators and their main options:

demo generate-binding typescript --path target/generated/typescript
demo generate-binding typescript --zod --node --module-name demo-node --path target/generated/typescript-node
demo generate-binding flow --path target/generated/flow
demo generate-binding flow --zod --node --module-name demo-node --path target/generated/flow-node
demo generate-binding python --module-name demo_bindings --namespace Demo --path target/generated/python
demo generate-binding python --full-module --module-name demo --namespace Demo --path target/generated/python-package
demo generate-binding rust --module-name demo_bindings --output-contracts --path target/generated/rust
demo generate-binding kotlin --module-name demo_bindings --package dev.example.demo --path target/generated/kotlin

See examples/generate_binding_subcommand.rs for a complete app-shaped example.

Builder API CLIs

Builder-style clap apps can pass a Command directly:

use std::path::PathBuf;

use clap::{Arg, ArgAction, Command, ValueHint, value_parser};
use clap_types::{generate_to, Python, TypeScript};

fn cli() -> Command {
    Command::new("repo-agent")
        .arg(
            Arg::new("workspace")
                .long("workspace")
                .global(true)
                .value_hint(ValueHint::DirPath)
                .value_parser(value_parser!(PathBuf))
                .action(ArgAction::Set),
        )
        .subcommand(
            Command::new("index")
                .arg(Arg::new("input").required(true))
                .arg(Arg::new("threads").long("threads").value_parser(value_parser!(u16))),
        )
}

let cmd = cli();
generate_to(TypeScript::new(), &cmd, "repo-agent", "target/generated/typescript")?;

let cmd = cli();
generate_to(
    Python::new().module_name("repo_agent_bindings").namespace("RepoAgent"),
    &cmd,
    "repo-agent",
    "target/generated/python",
)?;
# Ok::<(), std::io::Error>(())

Derive API CLIs

Derive-style clap apps work by using CommandFactory::command():

use clap::{CommandFactory, Parser, Subcommand, ValueEnum};
use clap_types::{generate_to, TypeScript};

#[derive(Parser)]
#[command(name = "opsctl")]
struct OpsCtl {
    #[arg(long, global = true, value_enum, default_value = "table")]
    output: OutputFormat,

    #[command(subcommand)]
    command: OpsCommand,
}

#[derive(Subcommand)]
enum OpsCommand {
    Deploy {
        service: String,
        #[arg(long, required = true)]
        image: String,
    },
}

#[derive(Clone, Copy, ValueEnum)]
enum OutputFormat {
    Table,
    Json,
}

let cmd = OpsCtl::command();
generate_to(TypeScript::new().zod(), &cmd, "opsctl", "target/generated/typescript-zod")?;
# Ok::<(), std::io::Error>(())

The full derive example is in examples/generate_derive_bindings.rs.

Generated TypeScript

Default TypeScript output has no runtime dependencies:

import {
  buildAgentRunCommand,
  type AgentRunArgs,
} from "./generated/repo-agent";

const args: AgentRunArgs = {
  workspace: "/repo",
  verbose: 2,
  task: "summarize",
  maxTokens: 2048,
  dryRun: true,
};

const argv = buildAgentRunCommand(args);

Clap metadata is translated conservatively:

ValueEnum and possible values become string literal unions.
flags become boolean;
counters become number;
integer and float parsers become number;
repeated options become readonly arrays;
required clap values become required TypeScript properties;
global args are inherited into subcommand builders.

Generated TypeScript + Zod

Use Zod mode when runtime validation is useful:

use clap_types::TypeScript;

let generator = TypeScript::new()
    .module_name("repo-agent-zod")
    .zod();

Zod output emits strict schemas and inferred types:

import {
  AgentRunArgsSchema,
  buildAgentRunCommand,
  type AgentRunArgs,
} from "./generated/repo-agent-zod";

const parsed = AgentRunArgsSchema.parse({
  task: "summarize",
  model: "frontier",
});

const argv = buildAgentRunCommand(parsed);

TypeScript::new().zod() validates builder inputs with Schema.parse(args). TypeScript::new().zod_schemas() emits schemas and inferred types without parsing inside the builder.

Generated TypeScript + Node

Use Node mode when the generated artifact should include idiomatic node:child_process helpers:

use clap_types::TypeScript;

let generator = TypeScript::new()
    .module_name("repo-agent-node")
    .node();

The generated module still exposes the plain argv builder, and adds process-ready helpers:

import {
  createAgentRunCommand,
  runAgentRunCommand,
  type AgentRunArgs,
} from "./generated/repo-agent-node";

const args: AgentRunArgs = {
  task: "summarize",
  model: "frontier",
};

const command = createAgentRunCommand(args);
// { file: "repo-agent", args: ["agent", "run", "summarize", "--model", "frontier"] }

const result = await runAgentRunCommand(args, { cwd: "/repo" });
console.log(result.stdout);

create...Command returns { file, args }, run...Command uses execFile, and spawn...Command uses spawn. Pass { program: "/custom/path" } to override the executable while keeping the typed argv builder unchanged.

Generated Flow

Flow output mirrors the TypeScript backend but emits runnable .js modules with Flow annotations:

use clap_types::Flow;

let generator = Flow::new().module_name("repo-agent");
let zod_generator = Flow::new().module_name("repo-agent-zod").zod();
let node_generator = Flow::new().module_name("repo-agent-node").node();

The generated JavaScript uses exact object types, ReadonlyArray for repeated values, optional Zod schemas, and optional Node child_process helpers. Every generated module starts with a /** @generated @flow strict */ header so downstream tooling and linters recognize the file as generated. Runtime tests strip Flow annotations with flow-remove-types before executing under Node or Bun.

Generated Python

Python output targets Python 3.10 through 3.14 and uses only the standard library:

from repo_agent_bindings import AgentRunArgs, RepoAgent

args = AgentRunArgs(
    workspace="/repo",
    verbose=2,
    task="summarize",
    model="frontier",
    max_tokens=2048,
    dry_run=True,
)

invocation = RepoAgent.agent_run_command(args, program="repo-agent")
argv = invocation.argv()

Python generated clients include:

frozen keyword-only dataclasses;
Literal[...] for possible values;
int, float, bool, and path-like annotations when clap exposes those parser types;
build_..._args() functions returning tuple[str, ...];
..._command() helpers returning CommandInvocation;
CommandInvocation.run() as a thin subprocess.run wrapper.

Python can also generate a package layout:

use clap::Command;
use clap_types::{generate_to, Python};

fn build_cli() -> Command {
    Command::new("repo-agent")
}

let cmd = build_cli();
generate_to(
    Python::new()
        .module_name("repo_agent")
        .namespace("RepoAgent")
        .package(),
    &cmd,
    "repo-agent",
    "target/generated/python-package",
)?;
# Ok::<(), std::io::Error>(())

The package layout emits _runtime.py, _root.py, and command modules such as agent/run.py:

from repo_agent.agent.run import Args, command

invocation = command(Args(task="summarize", model="frontier"))
assert invocation.argv() == ["repo-agent", "agent", "run", "summarize", "--model", "frontier"]

Generated Rust

Rust output uses only std:

use repo_agent_bindings::{AgentRunArgs, AgentRunModel, build_agent_run_command};

let args = AgentRunArgs {
    task: "summarize".to_owned(),
    model: Some(AgentRunModel::Frontier),
    dry_run: true,
    ..Default::default()
};

let argv = build_agent_run_command(&args);

The backend emits structs for command args, enums for clap possible values, build_..._command() functions, and CommandInvocation helpers over std::process::Command.

Generated Kotlin

Kotlin output targets Kotlin/JVM desktop clients and uses the standard library:

val args =
    AgentRunArgs(
        task = "summarize",
        model = AgentRunModel.Frontier,
        dryRun = true,
    )

val invocation = agentRunCommand(args)
val process = invocation.processBuilder().start()

The backend emits data classes, enum classes, build...Command() functions, and a small CommandInvocation wrapper around ProcessBuilder.

Output Contracts

All generators omit output contracts by default. Turn them on when the reflected CliSpec includes explicit output metadata:

let generator = TypeScript::new().output_contracts();
let generator = Flow::new().output_contracts();
let generator = Python::new().output_contracts();
let generator = Rust::new().output_contracts();
let generator = Kotlin::new().output_contracts();

Generated parsers stay dependency-free. They preserve JSON as parsed unknown in TypeScript and Flow (both call the runtime's built-in JSON.parse), use json.loads in Python, and expose framed JSON/JSON-lines strings in Rust and Kotlin so callers can pick their own deserialization library (serde_json/simd-json/sonic-rs for Rust; kotlinx.serialization/Jackson/ Moshi for Kotlin) and target type.

Structured Type Hints

Clap already exposes useful input metadata, and clap_types preserves it wherever it can:

PathBuf, OsString, and ValueHint::FilePath / ValueHint::DirPath can tell a backend that a string-like value is really a filesystem value;
ValueEnum and possible values become language-native enum or literal types;
integer, wide integer, float, boolean, repeated, grouped, and optional values keep their shape in generated clients.

The next step is explicit schema metadata for cases where clap cannot know enough. That should mirror output contracts: a command author can attach JSON Schema or small structured hints to an argument or output payload, and each backend can decide how much to render. TypeScript might emit Zod or JSON Schema validators, Python might expose TypedDict or dataclass adapters, Rust might support serde-aware modes, and Kotlin might support kotlinx.serialization. The default path should stay dependency-free, while schema-aware modes can be opt-in.

In other words: clap reflection should provide the baseline type shape; explicit schemas should provide richer semantic contracts such as "this string is a file", "this JSON field is a path", or "this output is a stream of objects with this schema."

Examples

Generate all fixtures:

npm run generate:fixtures

This runs:

examples/generate_complex_bindings.rs: builder-style clap examples;
examples/generate_derive_bindings.rs: derive-macro clap example.

Client examples:

python examples/clients/python_repo_agent.py target/generated
python examples/clients/python_opsctl_derive.py target/generated
bun examples/clients/typescript_repo_agent.ts
bun examples/clients/typescript_zod_opsctl.ts
npm run test:generated:flow

See docs/examples.md for the full map.

Development

Rust checks:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo test --doc --all-features

Generated-code checks:

npm ci
npm run generate:fixtures
npm run check:generated:ts
npm run check:generated:flow
npm run lint:generated:rust
npm run check:generated:rust
npm run lint:generated:kotlin
npm run check:generated:kotlin
npm run test:generated:ts
npm run test:generated:flow
ruff check tests/generated/python_smoke.py tests/generated/python_package_smoke.py examples/clients/*.py target/generated/python target/generated/python-package
ruff format --check tests/generated/python_smoke.py tests/generated/python_package_smoke.py examples/clients/*.py target/generated/python target/generated/python-package
black --check tests/generated/python_smoke.py tests/generated/python_package_smoke.py examples/clients/*.py target/generated/python target/generated/python-package
python -m compileall -q target/generated/python target/generated/python-package tests/generated/python_smoke.py tests/generated/python_package_smoke.py examples/clients
python tests/generated/python_smoke.py target/generated
python tests/generated/python_package_smoke.py target/generated

CI runs Rust checks, Python generated-code checks on Python 3.10 through 3.14, TypeScript and Flow checks on Node plus Bun, generated Rust compilation, and generated Kotlin/JVM compilation. Generated Rust is checked with rustfmt, cargo clippy, and rustc -D warnings; generated Kotlin is compiled with -Werror, -Wextra, progressive mode, and bytecode validation so compiler deprecations become CI failures instead of quiet drift.

Design Notes

clap_types treats clap as the source of truth for inputs. It does not infer stdout or stderr contracts from help text. Structured output should be declared explicitly; see docs/output-contracts.md.

Output contracts that attach metadata directly to clap::Command use clap's unstable extension API and are gated behind clap_types' own unstable-output-contracts feature. The stable IR can already carry JSON, JSON-lines, text, buffered, streaming, interactive, and JSON Schema metadata.

More design detail lives in:

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
.flowconfig		.flowconfig
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
README.md		README.md
SECURITY.md		SECURITY.md
cspell.json		cspell.json
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

clap_types

Status

What You Get

Install

Quick Start

Hidden Binding Command

Builder API CLIs

Derive API CLIs

Generated TypeScript

Generated TypeScript + Zod

Generated TypeScript + Node

Generated Flow

Generated Python

Generated Rust

Generated Kotlin

Output Contracts

Structured Type Hints

Examples

Development

Design Notes

License

Contribution

About

Licenses found

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

clap_types

Status

What You Get

Install

Quick Start

Hidden Binding Command

Builder API CLIs

Derive API CLIs

Generated TypeScript

Generated TypeScript + Zod

Generated TypeScript + Node

Generated Flow

Generated Python

Generated Rust

Generated Kotlin

Output Contracts

Structured Type Hints

Examples

Development

Design Notes

License

Contribution

About

Topics

Resources

License

Licenses found

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages