diff --git a/Cargo.lock b/Cargo.lock
index 51d0e89a..a0263565 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2174,6 +2174,7 @@ dependencies = [
  "serde",
  "shell-words",
  "strum",
+ "tempfile",
  "tera",
  "thiserror",
  "versions",
diff --git a/cli/assets/fig.ts b/cli/assets/fig.ts
index 433bb830..29499a60 100644
--- a/cli/assets/fig.ts
+++ b/cli/assets/fig.ts
@@ -456,6 +456,55 @@ const completionSpec: Fig.Spec = {
             },
           ],
         },
+        {
+          name: "sdk",
+          description: "Generate a type-safe SDK from a usage spec",
+          options: [
+            {
+              name: ["-f", "--file"],
+              description: "A usage spec taken in as a file",
+              isRepeatable: false,
+              args: {
+                name: "file",
+                template: "filepaths",
+              },
+            },
+            {
+              name: ["-l", "--language"],
+              description: "Target language for the SDK",
+              isRepeatable: false,
+              args: {
+                name: "language",
+                suggestions: ["typescript", "python"],
+              },
+            },
+            {
+              name: ["-o", "--output"],
+              description: "Output directory for generated SDK files",
+              isRepeatable: false,
+              args: {
+                name: "output",
+              },
+            },
+            {
+              name: ["-p", "--package-name"],
+              description:
+                "Override the package/module name (defaults to spec bin name)",
+              isRepeatable: false,
+              args: {
+                name: "package_name",
+              },
+            },
+            {
+              name: "--spec",
+              description: "Raw string spec input",
+              isRepeatable: false,
+              args: {
+                name: "spec",
+              },
+            },
+          ],
+        },
       ],
     },
     {
diff --git a/cli/assets/usage.1 b/cli/assets/usage.1
index 6320211c..0055e5f8 100644
--- a/cli/assets/usage.1
+++ b/cli/assets/usage.1
@@ -69,6 +69,9 @@ Generate markdown documentation from usage specs
 \fIAliases: \fRmd
 .RE
 .TP
+\fBgenerate sdk\fR
+Generate a type\-safe SDK from a usage spec
+.TP
 \fBlint\fR
 Lint a usage spec file for common issues
 .TP
@@ -310,6 +313,28 @@ Replace `<pre>` tags with markdown code fences
 .TP
 \fB\-\-url\-prefix\fR \fI<URL_PREFIX>\fR
 Prefix to add to all URLs
+.SH "USAGE GENERATE SDK"
+Generate a type\-safe SDK from a usage spec
+.PP
+\fBUsage:\fR usage generate sdk [OPTIONS]
+.PP
+\fBOptions:\fR
+.PP
+.TP
+\fB\-f, \-\-file\fR \fI<FILE>\fR
+A usage spec taken in as a file
+.TP
+\fB\-l, \-\-language\fR \fI<LANGUAGE>\fR
+Target language for the SDK
+.TP
+\fB\-o, \-\-output\fR \fI<OUTPUT>\fR
+Output directory for generated SDK files
+.TP
+\fB\-p, \-\-package\-name\fR \fI<PACKAGE_NAME>\fR
+Override the package/module name (defaults to spec bin name)
+.TP
+\fB\-\-spec\fR \fI<SPEC>\fR
+Raw string spec input
 .SH "USAGE LINT"
 Lint a usage spec file for common issues
 .PP
diff --git a/cli/src/cli/generate/mod.rs b/cli/src/cli/generate/mod.rs
index 4943bc8b..38d6b5e5 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -10,6 +10,7 @@ mod fig;
 mod json;
 mod manpage;
 mod markdown;
+mod sdk;
 
 /// Generate completions, documentation, and other artifacts from usage specs
 #[derive(clap::Args)]
@@ -27,6 +28,7 @@ pub enum Command {
     Json(json::Json),
     Manpage(manpage::Manpage),
     Markdown(markdown::Markdown),
+    Sdk(sdk::Sdk),
 }
 
 impl Generate {
@@ -38,6 +40,7 @@ impl Generate {
             Command::Json(cmd) => cmd.run(),
             Command::Manpage(cmd) => cmd.run(),
             Command::Markdown(cmd) => cmd.run(),
+            Command::Sdk(cmd) => cmd.run(),
         }
     }
 }
diff --git a/cli/src/cli/generate/sdk.rs b/cli/src/cli/generate/sdk.rs
new file mode 100644
index 00000000..76949eb6
--- /dev/null
+++ b/cli/src/cli/generate/sdk.rs
@@ -0,0 +1,66 @@
+use std::path::PathBuf;
+
+use clap::Args;
+
+use crate::cli::generate;
+
+use usage::sdk::{SdkLanguage, SdkOptions};
+
+#[derive(Args)]
+#[clap(about = "Generate a type-safe SDK from a usage spec")]
+pub struct Sdk {
+    /// A usage spec taken in as a file
+    #[clap(short, long)]
+    file: Option<PathBuf>,
+
+    /// Target language for the SDK
+    #[clap(short, long, value_parser = ["typescript", "python"])]
+    language: String,
+
+    /// Output directory for generated SDK files
+    #[clap(short, long)]
+    output: PathBuf,
+
+    /// Override the package/module name (defaults to spec bin name)
+    #[clap(short, long)]
+    package_name: Option<String>,
+
+    /// Raw string spec input
+    #[clap(long, required_unless_present = "file", overrides_with = "file")]
+    spec: Option<String>,
+}
+
+impl Sdk {
+    pub fn run(&self) -> miette::Result<()> {
+        let spec = generate::file_or_spec(&self.file, &self.spec)?;
+
+        let language = match self.language.as_str() {
+            "typescript" => SdkLanguage::TypeScript,
+            "python" => SdkLanguage::Python,
+            other => {
+                return Err(miette::miette!("unsupported language: {other}"));
+            }
+        };
+
+        let source_file = self.file.as_ref().map(|p| p.display().to_string());
+
+        let opts = SdkOptions {
+            language,
+            package_name: self.package_name.clone(),
+            source_file,
+        };
+
+        let output = usage::sdk::generate(&spec, &opts);
+
+        std::fs::create_dir_all(&self.output)
+            .map_err(|e| miette::miette!("failed to create output directory: {e}"))?;
+
+        for file in &output.files {
+            let path = self.output.join(&file.path);
+            println!("writing to {}", path.display());
+            xx::file::write(&path, &file.content)?;
+        }
+
+        Ok(())
+    }
+}
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index 5bea24b1..cabaaf46 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -135,6 +135,25 @@ cmd generate subcommand_required=#true help="Generate completions, documentation
             arg <URL_PREFIX>
         }
     }
+    cmd sdk help="Generate a type-safe SDK from a usage spec" {
+        flag "-f --file" help="A usage spec taken in as a file" {
+            arg <FILE>
+        }
+        flag "-l --language" help="Target language for the SDK" required=#true {
+            arg <LANGUAGE> {
+                choices typescript python
+            }
+        }
+        flag "-o --output" help="Output directory for generated SDK files" required=#true {
+            arg <OUTPUT>
+        }
+        flag "-p --package-name" help="Override the package/module name (defaults to spec bin name)" {
+            arg <PACKAGE_NAME>
+        }
+        flag --spec help="Raw string spec input" {
+            arg <SPEC>
+        }
+    }
 }
 cmd lint help="Lint a usage spec file for common issues" {
     flag "-f --format" help="Output format" default=text {
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 4e029e35..c0a53f28 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -57,6 +57,7 @@ export default defineConfig({
           { text: "Completions", link: "/cli/completions" },
           { text: "Manpages", link: "/cli/manpages" },
           { text: "Markdown", link: "/cli/markdown" },
+          { text: "SDK Generation", link: "/cli/sdk" },
           { text: "Scripts", link: "/cli/scripts" },
           {
             text: "CLI Reference", link: "/cli/reference/", items:
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index b9565066..f7400728 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -740,6 +740,111 @@
             "aliases": ["md"],
             "hidden_aliases": [],
             "examples": []
+          },
+          "sdk": {
+            "full_cmd": ["generate", "sdk"],
+            "usage": "generate sdk <FLAGS>",
+            "subcommands": {},
+            "args": [],
+            "flags": [
+              {
+                "name": "file",
+                "usage": "-f --file <FILE>",
+                "help": "A usage spec taken in as a file",
+                "help_first_line": "A usage spec taken in as a file",
+                "short": ["f"],
+                "long": ["file"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "FILE",
+                  "usage": "<FILE>",
+                  "required": true,
+                  "double_dash": "Optional",
+                  "hide": false
+                }
+              },
+              {
+                "name": "language",
+                "usage": "-l --language <LANGUAGE>",
+                "help": "Target language for the SDK",
+                "help_first_line": "Target language for the SDK",
+                "short": ["l"],
+                "long": ["language"],
+                "required": true,
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "LANGUAGE",
+                  "usage": "<LANGUAGE>",
+                  "required": true,
+                  "double_dash": "Optional",
+                  "hide": false,
+                  "choices": {
+                    "choices": ["typescript", "python"]
+                  }
+                }
+              },
+              {
+                "name": "output",
+                "usage": "-o --output <OUTPUT>",
+                "help": "Output directory for generated SDK files",
+                "help_first_line": "Output directory for generated SDK files",
+                "short": ["o"],
+                "long": ["output"],
+                "required": true,
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "OUTPUT",
+                  "usage": "<OUTPUT>",
+                  "required": true,
+                  "double_dash": "Optional",
+                  "hide": false
+                }
+              },
+              {
+                "name": "package-name",
+                "usage": "-p --package-name <PACKAGE_NAME>",
+                "help": "Override the package/module name (defaults to spec bin name)",
+                "help_first_line": "Override the package/module name (defaults to spec bin name)",
+                "short": ["p"],
+                "long": ["package-name"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "PACKAGE_NAME",
+                  "usage": "<PACKAGE_NAME>",
+                  "required": true,
+                  "double_dash": "Optional",
+                  "hide": false
+                }
+              },
+              {
+                "name": "spec",
+                "usage": "--spec <SPEC>",
+                "help": "Raw string spec input",
+                "help_first_line": "Raw string spec input",
+                "short": [],
+                "long": ["spec"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "SPEC",
+                  "usage": "<SPEC>",
+                  "required": true,
+                  "double_dash": "Optional",
+                  "hide": false
+                }
+              }
+            ],
+            "mounts": [],
+            "hide": false,
+            "help": "Generate a type-safe SDK from a usage spec",
+            "name": "sdk",
+            "aliases": [],
+            "hidden_aliases": [],
+            "examples": []
           }
         },
         "args": [],
diff --git a/docs/cli/reference/generate.md b/docs/cli/reference/generate.md
index 00ea4d0e..2971788b 100644
--- a/docs/cli/reference/generate.md
+++ b/docs/cli/reference/generate.md
@@ -16,3 +16,4 @@ Generate completions, documentation, and other artifacts from usage specs
 - [`usage generate json [-f --file <FILE>] [--spec <SPEC>]`](/cli/reference/generate/json.md)
 - [`usage generate manpage <FLAGS>`](/cli/reference/generate/manpage.md)
 - [`usage generate markdown <FLAGS>`](/cli/reference/generate/markdown.md)
+- [`usage generate sdk <FLAGS>`](/cli/reference/generate/sdk.md)
diff --git a/docs/cli/reference/generate/sdk.md b/docs/cli/reference/generate/sdk.md
new file mode 100644
index 00000000..a1d2ab41
--- /dev/null
+++ b/docs/cli/reference/generate/sdk.md
@@ -0,0 +1,35 @@
+<!-- @generated by usage-cli from usage spec -->
+
+# `usage generate sdk`
+
+- **Usage**: `usage generate sdk <FLAGS>`
+- **Source code**: [`cli/src/cli/generate/sdk.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/sdk.rs)
+
+Generate a type-safe SDK from a usage spec
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `-l --language <LANGUAGE>`
+
+Target language for the SDK
+
+**Choices:**
+
+- `typescript`
+- `python`
+
+### `-o --output <OUTPUT>`
+
+Output directory for generated SDK files
+
+### `-p --package-name <PACKAGE_NAME>`
+
+Override the package/module name (defaults to spec bin name)
+
+### `--spec <SPEC>`
+
+Raw string spec input
diff --git a/docs/cli/reference/index.md b/docs/cli/reference/index.md
index fcb0ac6d..84694296 100644
--- a/docs/cli/reference/index.md
+++ b/docs/cli/reference/index.md
@@ -33,6 +33,7 @@ Outputs a `usage.kdl` spec for this CLI itself
 - [`usage generate json [-f --file <FILE>] [--spec <SPEC>]`](/cli/reference/generate/json.md)
 - [`usage generate manpage <FLAGS>`](/cli/reference/generate/manpage.md)
 - [`usage generate markdown <FLAGS>`](/cli/reference/generate/markdown.md)
+- [`usage generate sdk <FLAGS>`](/cli/reference/generate/sdk.md)
 - [`usage lint [-f --format <FORMAT>] [-W --warnings-as-errors] <FILE>`](/cli/reference/lint.md)
 - [`usage powershell [-h] [--help] <SCRIPT> [ARGS]…`](/cli/reference/powershell.md)
 - [`usage zsh [-h] [--help] <SCRIPT> [ARGS]…`](/cli/reference/zsh.md)
diff --git a/docs/cli/sdk.md b/docs/cli/sdk.md
new file mode 100644
index 00000000..cb9c06ba
--- /dev/null
+++ b/docs/cli/sdk.md
@@ -0,0 +1,145 @@
+# Generating Type-Safe SDKs
+
+Usage CLI can generate type-safe SDK client libraries from a Usage spec. The generated SDK is a
+**subprocess wrapper** -- it invokes your CLI binary via `subprocess.run` / `child_process.spawn`,
+not a native binding. It provides type definitions for arguments, flags,
+and choices, along with a client that constructs the correct CLI argument list for you.
+
+## When to Use This
+
+### CLIs without language bindings
+
+Popular tools like ffmpeg have hand-written bindings in many languages, but the vast majority of CLI
+tools don't. For tools like `restic`, `rclone`, `pandoc`, `age`, or any internal CLI, the only
+option has been to manually construct argument lists:
+
+```python
+# before: stringly-typed, no autocomplete, typos slip through
+subprocess.run(["rclone", "copy", src, dst, "--progress", "--transfers", "4"])
+```
+
+With a generated SDK:
+
+```python
+# after: typed, autocomplete, mistakes caught at lint time
+rclone.copy(src, dst, progress=True, transfers=4)
+```
+
+### Stay in sync with CLI versions
+
+Hand-written bindings drift out of date when the CLI evolves. Generated SDKs solve this the same way
+Protobuf/gRPC does -- the spec is the source of truth, the SDK is a derived artifact:
+
+```sh
+# in CI, when you cut a new release:
+usage generate sdk -l python -o ./sdk/python/ -f ./mycli.usage.kdl
+git commit -m "chore: regenerate sdk from v2.3.0 spec"
+```
+
+### Internal platform CLIs
+
+This is the strongest use case. Companies typically have internal CLIs for deployment, config
+management, database migrations, etc. Teams in different languages (Python scripts, TypeScript
+services, Rust tools) all need to call these CLIs, and each team independently writes fragile
+subprocess calls. With a Usage spec, you generate typed SDKs for all languages from a single source
+of truth:
+
+```ts
+// auto-generated, always in sync with the CLI
+import { deploy } from "@internal/platform-sdk";
+const result = await deploy({ env: "prod", service: "api", replicas: 3 });
+//                        ^ typed, choices-constrained, required-checked
+```
+
+## Quick Start
+
+Given a spec file `mycli.usage.kdl`:
+
+```sh
+usage generate sdk -l typescript -o ./sdk -f ./mycli.usage.kdl
+```
+
+This generates a complete SDK in the `./sdk` directory, ready to use:
+
+```ts
+import { Mycli } from "./sdk";
+
+const cli = new Mycli();
+const result = await cli.build.exec(
+  { target: "release", output: "./dist" },
+  { release: true }
+);
+if (result.ok) {
+  console.log(result.stdout);
+}
+```
+
+## Supported Languages
+
+| Language   | Flag            | Output Files                                         |
+| ---------- | --------------- | ---------------------------------------------------- |
+| TypeScript | `-l typescript` | `types.ts`, `client.ts`, `runtime.ts`, `index.ts`    |
+| Python     | `-l python`     | `types.py`, `client.py`, `runtime.py`, `__init__.py` |
+| Rust       | Coming soon     |                                                      |
+
+### TypeScript
+
+```sh
+usage generate sdk -l typescript -o ./sdk -f ./mycli.usage.kdl
+```
+
+Generates ES module files with full type annotations. The client uses `spawn` from
+`node:child_process` under the hood and all `exec()` methods are async, returning
+`Promise<CliResult>`.
+
+```ts
+import { Mycli, BuildArgs, BuildFlags } from "./sdk";
+
+const cli = new Mycli();
+const result = await cli.build.exec(
+  { target: "release", output: "./dist" } as BuildArgs,
+  { release: true } as BuildFlags
+);
+```
+
+### Python
+
+```sh
+usage generate sdk -l python -o ./sdk -f ./mycli.usage.kdl
+```
+
+Generates a Python package with `@dataclass` type definitions and type annotations. The client uses
+`subprocess.run` under the hood.
+
+```python
+from sdk import Mycli, BuildArgs, BuildFlags
+
+cli = Mycli()
+result = cli.build.exec(
+    BuildArgs(target="release", output="./dist"),
+    BuildFlags(release=True)
+)
+if result.ok:
+    print(result.stdout)
+```
+
+### Rust
+
+_Rust SDK support is coming soon._
+
+## How It Works
+
+Each generated SDK consists of three parts:
+
+1. **Types module** -- Type definitions for every command's args and flags. Choice constraints are
+   rendered as union types (TypeScript) or `Literal` types (Python).
+   Global flags are propagated to all subcommand flag types.
+
+2. **Client module** -- A nested class/struct hierarchy mirroring the subcommand tree. Each node has
+   an `exec()` method that constructs the CLI argument list and invokes the binary. Flag arguments
+   are built via a helper method that handles value flags, boolean flags, count flags, negate flags,
+   and repeatable flags.
+
+3. **Runtime module** -- A small, static module containing `CliResult` (stdout, stderr, exit code)
+   and `CliRunner` (the subprocess invocation logic). This module is identical across all SDKs
+   generated from the same language target.
diff --git a/docs/spec/index.md b/docs/spec/index.md
index 1c624eee..d8514062 100644
--- a/docs/spec/index.md
+++ b/docs/spec/index.md
@@ -8,6 +8,7 @@ for CLIs. Here are some potential reasons for defining your CLI with a Usage spe
 - Generate autocompletion scripts
 - Generate markdown documentation
 - Generate man pages
+- Generate type-safe SDK client libraries for TypeScript, Python, and Rust
 - Use an advanced arg parser in any language
 - Scaffold one spec into different CLI frameworks—even different languages
 - [coming soon] Host your CLI documentation on usage.sh
diff --git a/lib/Cargo.toml b/lib/Cargo.toml
index e7d4ab7e..e9923fee 100644
--- a/lib/Cargo.toml
+++ b/lib/Cargo.toml
@@ -40,9 +40,10 @@ versions = "7"
 xx = "2"
 
 [features]
-default = ["docs"]
+default = ["docs", "sdk"]
 docs = ["tera", "roff"]
 unstable_choices_env = []
+sdk = []
 
 [dev-dependencies]
 criterion = "0.8"
@@ -50,6 +51,7 @@ ctor = "0.10"
 insta = "1"
 pretty_assertions = "1"
 shell-words = "1"
+tempfile = "3"
 
 [[bench]]
 name = "parse"
diff --git a/lib/src/lib.rs b/lib/src/lib.rs
index dbda03b2..19524b3a 100644
--- a/lib/src/lib.rs
+++ b/lib/src/lib.rs
@@ -24,6 +24,8 @@ pub use error::Result;
 #[cfg(feature = "docs")]
 pub mod docs;
 pub mod parse;
+#[cfg(feature = "sdk")]
+pub mod sdk;
 pub(crate) mod sh;
 pub(crate) mod string;
 #[cfg(test)]
diff --git a/lib/src/sdk/mod.rs b/lib/src/sdk/mod.rs
new file mode 100644
index 00000000..c828c18d
--- /dev/null
+++ b/lib/src/sdk/mod.rs
@@ -0,0 +1,438 @@
+use std::fmt;
+
+use std::path::PathBuf;
+
+use heck::AsPascalCase;
+use indexmap::IndexMap;
+
+use crate::spec::cmd::SpecCommand;
+use crate::Spec;
+
+pub mod python;
+pub mod typescript;
+
+#[derive(Debug, Clone)]
+pub enum SdkLanguage {
+    TypeScript,
+    Python,
+}
+
+#[derive(Debug, Clone)]
+pub struct SdkOptions {
+    pub language: SdkLanguage,
+    pub package_name: Option<String>,
+    pub source_file: Option<String>,
+}
+
+#[derive(Debug)]
+pub struct SdkOutput {
+    pub files: Vec<SdkFile>,
+}
+
+#[derive(Debug)]
+pub struct SdkFile {
+    pub path: PathBuf,
+    pub content: String,
+}
+
+pub fn generate(spec: &Spec, opts: &SdkOptions) -> SdkOutput {
+    match opts.language {
+        SdkLanguage::TypeScript => typescript::generate(spec, opts),
+        SdkLanguage::Python => python::generate(spec, opts),
+    }
+}
+
+/// Escape JSDoc-terminating sequences in comment text.
+pub(crate) fn escape_jsdoc(s: &str) -> String {
+    s.replace("*/", r"*\/")
+}
+
+/// Escape triple-quote sequences in Python docstrings.
+pub(crate) fn escape_py_docstring(s: &str) -> String {
+    s.replace(r#"""""#, r#"\"\"\""#)
+}
+
+/// Escape backslashes and double quotes for Python string literals.
+pub(crate) fn escape_py_string(s: &str) -> String {
+    s.replace('\\', r"\\").replace('"', r#"\""#)
+}
+
+/// Escape backslashes and double quotes for TypeScript string literals.
+pub(crate) fn escape_ts_string(s: &str) -> String {
+    s.replace('\\', r"\\").replace('"', r#"\""#)
+}
+
+/// A simple code writer with indentation management.
+pub(crate) struct CodeWriter {
+    buf: String,
+    indent: usize,
+    indent_str: &'static str,
+}
+
+impl CodeWriter {
+    pub fn new() -> Self {
+        Self {
+            buf: String::new(),
+            indent: 0,
+            indent_str: "  ",
+        }
+    }
+
+    /// Create a CodeWriter with custom indent string (e.g. "    " for Python).
+    pub fn with_indent(indent_str: &'static str) -> Self {
+        Self {
+            buf: String::new(),
+            indent: 0,
+            indent_str,
+        }
+    }
+
+    pub fn line(&mut self, s: &str) {
+        if !s.is_empty() {
+            for _ in 0..self.indent {
+                self.buf.push_str(self.indent_str);
+            }
+        }
+        self.buf.push_str(s);
+        self.buf.push('\n');
+    }
+
+    pub fn indent(&mut self) {
+        self.indent += 1;
+    }
+
+    pub fn dedent(&mut self) {
+        self.indent = self.indent.saturating_sub(1);
+    }
+
+    pub fn finish(self) -> String {
+        self.buf
+    }
+}
+
+impl fmt::Display for CodeWriter {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.buf)
+    }
+}
+
+pub(crate) fn generated_header(comment_prefix: &str, source: &Option<String>) -> String {
+    match source {
+        Some(s) => {
+            format!("{comment_prefix} @generated by usage-cli from {s}. Do not edit manually.")
+        }
+        None => format!("{comment_prefix} @generated by usage-cli. Do not edit manually."),
+    }
+}
+
+/// Returns the PascalCase type name for a command: the command name, or the package name for root.
+pub(crate) fn command_type_name(cmd: &SpecCommand, package_name: &str) -> String {
+    if cmd.name.is_empty() {
+        AsPascalCase(package_name).to_string()
+    } else {
+        AsPascalCase(&cmd.name).to_string()
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Choice type collection with collision detection
+// ---------------------------------------------------------------------------
+
+/// Maps choice type definitions and provides collision-aware type name lookup.
+///
+/// When two commands have the same arg/flag name with different choices,
+/// the type name is prefixed with the command's PascalCase name to avoid collision.
+pub(crate) struct ChoiceTypeMap {
+    /// Resolved type name -> choice values
+    pub types: IndexMap<String, Vec<String>>,
+    /// (cmd_name, item_name) -> resolved type name
+    name_map: IndexMap<(String, String), String>,
+}
+
+impl ChoiceTypeMap {
+    /// Look up the resolved type name for a choice arg/flag.
+    /// `cmd_name` is the command's name (empty string for root).
+    /// `item_name` is the arg or flag name.
+    pub fn lookup(&self, cmd_name: &str, item_name: &str) -> Option<&str> {
+        self.name_map
+            .get(&(cmd_name.to_string(), item_name.to_string()))
+            .map(|s| s.as_str())
+    }
+
+    /// Iterate over type definitions (name, choices).
+    pub fn iter(&self) -> indexmap::map::Iter<'_, String, Vec<String>> {
+        self.types.iter()
+    }
+
+    /// Check if there are no choice types.
+    pub fn is_empty(&self) -> bool {
+        self.types.is_empty()
+    }
+}
+
+struct ChoiceEntry {
+    base_name: String,
+    item_name: String,
+    cmd_name: String,
+    cmd_prefix: String,
+    choices: Vec<String>,
+}
+
+/// Collects all unique choice types across a command tree.
+/// When two commands have the same arg/flag name with different choices,
+/// the type name is prefixed with the command's PascalCase name to avoid collision.
+pub(crate) fn collect_choice_types(cmd: &SpecCommand) -> ChoiceTypeMap {
+    let mut all_entries: Vec<ChoiceEntry> = Vec::new();
+    collect_choice_entries(cmd, &mut all_entries);
+
+    // Group by base type name, check for choice differences
+    let mut base_groups: IndexMap<String, Vec<&ChoiceEntry>> = IndexMap::new();
+    for entry in &all_entries {
+        base_groups
+            .entry(entry.base_name.clone())
+            .or_default()
+            .push(entry);
+    }
+
+    let mut types = IndexMap::new();
+    let mut name_map = IndexMap::new();
+    for (base_name, entries) in &base_groups {
+        let all_same = entries.windows(2).all(|w| w[0].choices == w[1].choices);
+        if all_same {
+            types.insert(base_name.clone(), entries[0].choices.clone());
+            for entry in entries {
+                name_map.insert(
+                    (entry.cmd_name.clone(), entry.item_name.clone()),
+                    base_name.clone(),
+                );
+            }
+        } else {
+            for entry in entries {
+                let prefixed = format!("{}{}", entry.cmd_prefix, base_name);
+                types.insert(prefixed.clone(), entry.choices.clone());
+                name_map.insert((entry.cmd_name.clone(), entry.item_name.clone()), prefixed);
+            }
+        }
+    }
+
+    ChoiceTypeMap { types, name_map }
+}
+
+fn collect_choice_entries(cmd: &SpecCommand, entries: &mut Vec<ChoiceEntry>) {
+    if cmd.hide {
+        return;
+    }
+
+    let cmd_prefix = if cmd.name.is_empty() {
+        String::new()
+    } else {
+        AsPascalCase(&cmd.name).to_string()
+    };
+    let cmd_name = cmd.name.clone();
+
+    for arg in &cmd.args {
+        if arg.hide {
+            continue;
+        }
+        if let Some(choices) = &arg.choices {
+            let base_name = format!("{}Choice", AsPascalCase(&arg.name));
+            entries.push(ChoiceEntry {
+                base_name,
+                item_name: arg.name.clone(),
+                cmd_name: cmd_name.clone(),
+                cmd_prefix: cmd_prefix.clone(),
+                choices: choices.choices.clone(),
+            });
+        }
+    }
+
+    for flag in &cmd.flags {
+        if flag.hide {
+            continue;
+        }
+        if let Some(arg) = &flag.arg {
+            if let Some(choices) = &arg.choices {
+                let base_name = format!("{}Choice", AsPascalCase(&flag.name));
+                entries.push(ChoiceEntry {
+                    base_name,
+                    item_name: flag.name.clone(),
+                    cmd_name: cmd_name.clone(),
+                    cmd_prefix: cmd_prefix.clone(),
+                    choices: choices.choices.clone(),
+                });
+            }
+        }
+    }
+
+    for subcmd in cmd.subcommands.values() {
+        collect_choice_entries(subcmd, entries);
+    }
+}
+
+/// Collects type names that need to be imported from the types module.
+pub(crate) fn collect_type_imports(
+    cmd: &SpecCommand,
+    package_name: &str,
+    choice_types: &ChoiceTypeMap,
+) -> Vec<String> {
+    let mut imports = Vec::new();
+    collect_type_imports_recursive(cmd, package_name, choice_types, &mut imports);
+    imports.sort();
+    imports.dedup();
+    imports
+}
+
+fn collect_type_imports_recursive(
+    cmd: &SpecCommand,
+    package_name: &str,
+    choice_types: &ChoiceTypeMap,
+    imports: &mut Vec<String>,
+) {
+    if cmd.hide {
+        return;
+    }
+
+    let name = command_type_name(cmd, package_name);
+    let has_args = cmd.args.iter().any(|a| !a.hide);
+    let has_flags = cmd.flags.iter().any(|f| !f.hide);
+
+    if has_args {
+        imports.push(format!("{name}Args"));
+    }
+    if has_flags {
+        imports.push(format!("{name}Flags"));
+    }
+
+    for arg in &cmd.args {
+        if !arg.hide && arg.choices.is_some() {
+            if let Some(type_name) = choice_types.lookup(&cmd.name, &arg.name) {
+                imports.push(type_name.to_string());
+            }
+        }
+    }
+    for flag in &cmd.flags {
+        if !flag.hide {
+            if let Some(arg) = &flag.arg {
+                if arg.choices.is_some() {
+                    if let Some(type_name) = choice_types.lookup(&cmd.name, &flag.name) {
+                        imports.push(type_name.to_string());
+                    }
+                }
+            }
+        }
+    }
+
+    for subcmd in cmd.subcommands.values() {
+        collect_type_imports_recursive(subcmd, package_name, choice_types, imports);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_code_writer_display() {
+        let mut w = CodeWriter::with_indent("    ");
+        w.line("hello");
+        w.line("world");
+        let displayed = format!("{w}");
+        assert!(displayed.contains("hello"));
+        assert!(displayed.contains("world"));
+    }
+
+    #[test]
+    fn test_command_type_name_empty() {
+        let cmd = SpecCommand::default();
+        assert!(cmd.name.is_empty());
+        let result = command_type_name(&cmd, "mypackage");
+        assert_eq!(result, "Mypackage");
+    }
+
+    #[test]
+    fn test_generated_header_with_source() {
+        let result = generated_header("//", &Some("test.kdl".to_string()));
+        assert!(result.contains("test.kdl"));
+    }
+
+    #[test]
+    fn test_generated_header_without_source() {
+        let result = generated_header("//", &None);
+        assert!(!result.contains("test.kdl"));
+        assert!(result.contains("@generated"));
+    }
+
+    /// Hidden command with choices — covers collect_choice_entries skip paths
+    /// and collect_type_imports_recursive cmd.hide path.
+    #[test]
+    fn test_hidden_command_with_choices() {
+        let spec: crate::Spec = r##"
+            bin "app"
+            cmd "visible" help="Visible" {
+                arg "env" help="Environment" {
+                    choices "dev" "prod"
+                }
+            }
+            cmd "hidden" hide=#true help="Hidden" {
+                arg "mode" help="Mode" {
+                    choices "fast" "slow"
+                }
+                flag "--level <n>" help="Level" {
+                    choices "1" "2" "3"
+                }
+            }
+        "##
+        .parse()
+        .unwrap();
+        let choice_types = collect_choice_types(&spec.cmd);
+        // hidden command's choices should not be collected
+        assert!(choice_types.lookup("hidden", "mode").is_none());
+        assert!(choice_types.lookup("hidden", "level").is_none());
+        // visible command's choices should be collected
+        assert!(choice_types.lookup("visible", "env").is_some());
+    }
+
+    /// Hidden arg/flag with choices — covers skip paths in collect_choice_entries.
+    #[test]
+    fn test_hidden_arg_flag_with_choices() {
+        let spec: crate::Spec = r##"
+            bin "app"
+            arg "visible_choice" help="Visible" {
+                choices "a" "b"
+            }
+            arg "hidden_choice" hide=#true help="Hidden" {
+                choices "x" "y"
+            }
+            flag "--visible-flag <val>" help="Visible" {
+                choices "m" "n"
+            }
+            flag "--hidden-flag <val>" hide=#true help="Hidden" {
+                choices "p" "q"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let choice_types = collect_choice_types(&spec.cmd);
+        assert!(choice_types.lookup("app", "visible_choice").is_some());
+        assert!(choice_types.lookup("app", "hidden_choice").is_none());
+        assert!(choice_types.lookup("app", "visible-flag").is_some());
+        assert!(choice_types.lookup("app", "hidden-flag").is_none());
+    }
+
+    /// Flag with arg choices — covers flag.arg choices import path.
+    #[test]
+    fn test_flag_arg_choices_import() {
+        let spec: crate::Spec = r##"
+            bin "app"
+            flag "--shell <shell>" help="Shell type" {
+                choices "bash" "zsh" "fish"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let choice_types = collect_choice_types(&spec.cmd);
+        let mut imports = Vec::new();
+        collect_type_imports_recursive(&spec.cmd, "app", &choice_types, &mut imports);
+        assert!(imports.iter().any(|i| i.contains("Choice")));
+    }
+}
diff --git a/lib/src/sdk/python/mod.rs b/lib/src/sdk/python/mod.rs
new file mode 100644
index 00000000..e667e918
--- /dev/null
+++ b/lib/src/sdk/python/mod.rs
@@ -0,0 +1,1492 @@
+use std::path::PathBuf;
+
+use heck::AsPascalCase;
+
+use crate::sdk::{
+    collect_choice_types, collect_type_imports, command_type_name, escape_py_docstring,
+    escape_py_string, generated_header, ChoiceTypeMap, CodeWriter, SdkFile, SdkOptions, SdkOutput,
+};
+use crate::spec::arg::SpecDoubleDashChoices;
+use crate::spec::cmd::SpecCommand;
+use crate::spec::config::SpecConfigProp;
+use crate::spec::data_types::SpecDataTypes;
+use crate::{Spec, SpecArg, SpecFlag};
+
+mod runtime;
+
+pub fn generate(spec: &Spec, opts: &SdkOptions) -> SdkOutput {
+    let package_name = opts
+        .package_name
+        .clone()
+        .unwrap_or_else(|| spec.bin.clone());
+
+    SdkOutput {
+        files: vec![
+            SdkFile {
+                path: PathBuf::from("types.py"),
+                content: render_types(spec, &package_name, &opts.source_file),
+            },
+            SdkFile {
+                path: PathBuf::from("client.py"),
+                content: render_client(spec, &package_name, &opts.source_file),
+            },
+            SdkFile {
+                path: PathBuf::from("runtime.py"),
+                content: runtime::RUNTIME_PY.to_string(),
+            },
+            SdkFile {
+                path: PathBuf::from("__init__.py"),
+                content: render_init(&package_name),
+            },
+        ],
+    }
+}
+
+fn render_init(package_name: &str) -> String {
+    let class_name = AsPascalCase(package_name).to_string();
+    format!("from .client import {class_name}\nfrom .runtime import CliResult, CliRunner\nfrom .types import *\n")
+}
+
+// ---------------------------------------------------------------------------
+// types.py
+// ---------------------------------------------------------------------------
+
+fn render_types(spec: &Spec, package_name: &str, source_file: &Option<String>) -> String {
+    let mut w = CodeWriter::with_indent("    ");
+
+    w.line(&generated_header("#", source_file));
+    w.line("from __future__ import annotations");
+    w.line("from dataclasses import dataclass");
+    w.line("from typing import Literal, Optional, Union");
+    w.line("");
+
+    // spec metadata
+    if let Some(version) = &spec.version {
+        w.line(&format!("VERSION = \"{}\"", escape_py_string(version)));
+    }
+    if let Some(about) = &spec.about {
+        w.line(&format!("ABOUT = \"{}\"", escape_py_string(about)));
+    }
+    if let Some(author) = &spec.author {
+        w.line(&format!("AUTHOR = \"{}\"", escape_py_string(author)));
+    }
+
+    let choice_types = collect_choice_types(&spec.cmd);
+    let root_global_flags: Vec<&SpecFlag> = spec
+        .cmd
+        .flags
+        .iter()
+        .filter(|f| f.global && !f.hide)
+        .collect();
+    let has_global_flags = !root_global_flags.is_empty();
+
+    if !choice_types.is_empty() {
+        w.line("");
+        for (name, choices) in choice_types.iter() {
+            let union = choices
+                .iter()
+                .map(|c| format!("\"{}\"", escape_py_string(c)))
+                .collect::<Vec<_>>()
+                .join(", ");
+            w.line(&format!("{name} = Literal[{union}]"));
+        }
+    }
+
+    if has_global_flags {
+        w.line("");
+        render_flags_dataclass("GlobalFlags", "", &root_global_flags, &choice_types, &mut w);
+    }
+
+    render_command_types(
+        &spec.cmd,
+        package_name,
+        &choice_types,
+        has_global_flags,
+        &root_global_flags,
+        &mut w,
+    );
+
+    if !spec.config.props.is_empty() {
+        w.line("");
+        let config_name = format!("{}Config", AsPascalCase(package_name));
+        w.line("");
+        w.line("@dataclass");
+        w.line(&format!("class {config_name}:"));
+        w.indent();
+        // Python dataclass requires non-default fields before default fields
+        let (required, optional): (Vec<_>, Vec<_>) = spec
+            .config
+            .props
+            .iter()
+            .partition(|(_, p)| p.default.is_none());
+
+        for (name, prop) in required.iter().chain(optional.iter()) {
+            let py_type = config_prop_type(prop);
+            let default = if let Some(d) = &prop.default {
+                match prop.data_type {
+                    SpecDataTypes::Boolean => match d.as_str() {
+                        "#true" | "true" => " = True".to_string(),
+                        "#false" | "false" => " = False".to_string(),
+                        other => format!(" = {other}"),
+                    },
+                    SpecDataTypes::Integer | SpecDataTypes::Float => {
+                        let numeric = d.trim_matches('"');
+                        format!(" = {numeric}")
+                    }
+                    _ => format!(" = \"{}\"", escape_py_string(d)),
+                }
+            } else {
+                String::new()
+            };
+            if let Some(help) = &prop.help {
+                w.line(&format!("# {help}"));
+            }
+            w.line(&format!("{name}: {py_type}{default}"));
+        }
+        w.dedent();
+    }
+
+    w.finish()
+}
+
+fn render_command_types(
+    cmd: &SpecCommand,
+    package_name: &str,
+    choice_types: &ChoiceTypeMap,
+    has_global_flags: bool,
+    global_flags: &[&SpecFlag],
+    w: &mut CodeWriter,
+) {
+    if cmd.hide {
+        return;
+    }
+
+    let name = command_type_name(cmd, package_name);
+    let cmd_name = &cmd.name;
+    let visible_args: Vec<&SpecArg> = cmd.args.iter().filter(|a| !a.hide).collect();
+    let visible_flags: Vec<&SpecFlag> = cmd.flags.iter().filter(|f| !f.hide).collect();
+
+    if !visible_args.is_empty() {
+        w.line("");
+        render_args_dataclass(
+            &format!("{name}Args"),
+            cmd_name,
+            &visible_args,
+            choice_types,
+            w,
+        );
+    }
+
+    if !visible_flags.is_empty() {
+        w.line("");
+        let all_flags: Vec<&SpecFlag> = if has_global_flags {
+            global_flags
+                .iter()
+                .copied()
+                .chain(
+                    visible_flags
+                        .iter()
+                        .filter(|f| !global_flags.iter().any(|gf| gf.name == f.name))
+                        .copied(),
+                )
+                .collect()
+        } else {
+            visible_flags
+        };
+        render_flags_dataclass(
+            &format!("{name}Flags"),
+            cmd_name,
+            &all_flags,
+            choice_types,
+            w,
+        );
+    }
+
+    for subcmd in cmd.subcommands.values() {
+        render_command_types(
+            subcmd,
+            package_name,
+            choice_types,
+            has_global_flags,
+            global_flags,
+            w,
+        );
+    }
+}
+
+fn render_args_dataclass(
+    name: &str,
+    cmd_name: &str,
+    args: &[&SpecArg],
+    choice_types: &ChoiceTypeMap,
+    w: &mut CodeWriter,
+) {
+    w.line("");
+    w.line("@dataclass");
+    w.line(&format!("class {name}:"));
+    w.indent();
+    if args.is_empty() {
+        w.line("pass");
+    } else {
+        // Python dataclass requires non-default fields before default fields
+        let (required, optional): (Vec<_>, Vec<_>) = args
+            .iter()
+            .copied()
+            .partition(|a| a.required && a.default.is_empty());
+
+        for arg in required.iter().chain(optional.iter()) {
+            let py_type = arg_py_type(arg, cmd_name, choice_types);
+            let is_required_no_default = arg.required && arg.default.is_empty();
+            let field = if !is_required_no_default && !arg.default.is_empty() {
+                // has default value
+                let default_val = &arg.default[0];
+                format!(
+                    "{}: Optional[{}] = \"{}\"",
+                    sanitize_py_ident(&arg.name),
+                    py_type,
+                    escape_py_string(default_val)
+                )
+            } else if !is_required_no_default {
+                // optional without explicit default
+                format!(
+                    "{}: Optional[{}] = None",
+                    sanitize_py_ident(&arg.name),
+                    py_type
+                )
+            } else {
+                // required, no default
+                format!("{}: {}", sanitize_py_ident(&arg.name), py_type)
+            };
+            if let Some(help) = &arg.help {
+                w.line(&format!("# {help}"));
+            }
+            w.line(&field);
+        }
+    }
+    w.dedent();
+}
+
+fn render_flags_dataclass(
+    name: &str,
+    cmd_name: &str,
+    flags: &[&SpecFlag],
+    choice_types: &ChoiceTypeMap,
+    w: &mut CodeWriter,
+) {
+    w.line("");
+    w.line("@dataclass");
+    w.line(&format!("class {name}:"));
+    w.indent();
+    if flags.is_empty() {
+        w.line("pass");
+    } else {
+        // Python dataclass requires non-default fields before default fields
+        let (required, optional): (Vec<_>, Vec<_>) = flags
+            .iter()
+            .copied()
+            .partition(|f| f.required && f.default.is_empty());
+
+        for flag in required.iter().chain(optional.iter()) {
+            let py_type = flag_py_type(flag, cmd_name, choice_types);
+            let prop_name = flag_property_name_py(flag);
+            let optional = !(flag.required && flag.default.is_empty());
+            let field = if !flag.default.is_empty() {
+                // has explicit default — use first value
+                let default_val = &flag.default[0];
+                if flag.count {
+                    format!("{prop_name}: {py_type} = {default_val}")
+                } else if flag.arg.is_none() {
+                    // boolean with default
+                    match default_val.as_str() {
+                        "true" | "#true" => format!("{prop_name}: {py_type} = True"),
+                        "false" | "#false" => format!("{prop_name}: {py_type} = False"),
+                        _ => {
+                            // unrecognized boolean default — cannot emit as valid Python bool;
+                            // fall back to Optional[bool] = None with a comment
+                            format!("{prop_name}: Optional[bool] = None  # default: {default_val}")
+                        }
+                    }
+                } else if flag.var {
+                    // var value flag with default — cannot use list literal as default
+                    // (Python dataclass requires immutable defaults), use None with comment
+                    format!("{prop_name}: Optional[{py_type}] = None  # default: {default_val}")
+                } else {
+                    format!(
+                        "{prop_name}: Optional[{py_type}] = \"{}\"",
+                        escape_py_string(default_val)
+                    )
+                }
+            } else if optional {
+                format!("{prop_name}: Optional[{py_type}] = None")
+            } else {
+                format!("{prop_name}: {py_type}")
+            };
+            let mut doc_parts = Vec::new();
+            if let Some(help) = &flag.help {
+                doc_parts.push(help.clone());
+            }
+            if let Some(env) = &flag.env {
+                doc_parts.push(format!("Env: {env}"));
+            }
+            if let Some(deprecated) = &flag.deprecated {
+                doc_parts.push(format!("Deprecated: {deprecated}"));
+            }
+            if flag.long.len() > 1 {
+                let aliases: Vec<&str> = flag.long.iter().skip(1).map(|s| s.as_str()).collect();
+                doc_parts.push(format!("Aliases: {}", aliases.join(", ")));
+            }
+            if !flag.short.is_empty() {
+                let shorts: Vec<String> = flag.short.iter().map(|c| format!("-{c}")).collect();
+                doc_parts.push(format!("Short: {}", shorts.join(", ")));
+            }
+            if !doc_parts.is_empty() {
+                w.line(&format!("# {}", doc_parts.join(". ")));
+            }
+            w.line(&field);
+        }
+    }
+    w.dedent();
+}
+
+fn arg_py_type(arg: &SpecArg, cmd_name: &str, choice_types: &ChoiceTypeMap) -> String {
+    let base = if let Some(choices) = &arg.choices {
+        if let Some(resolved) = choice_types.lookup(cmd_name, &arg.name) {
+            resolved.to_string()
+        } else {
+            let union = choices
+                .choices
+                .iter()
+                .map(|c| format!("\"{}\"", escape_py_string(c)))
+                .collect::<Vec<_>>()
+                .join(", ");
+            format!("Literal[{union}]")
+        }
+    } else {
+        "str".to_string()
+    };
+
+    if arg.var {
+        format!("list[{base}]")
+    } else {
+        base
+    }
+}
+
+fn flag_py_type(flag: &SpecFlag, cmd_name: &str, choice_types: &ChoiceTypeMap) -> String {
+    if flag.count {
+        return "int".to_string();
+    }
+
+    match &flag.arg {
+        Some(arg) => {
+            let base = if let Some(choices) = &arg.choices {
+                if let Some(resolved) = choice_types.lookup(cmd_name, &flag.name) {
+                    resolved.to_string()
+                } else {
+                    let union = choices
+                        .choices
+                        .iter()
+                        .map(|c| format!("\"{}\"", escape_py_string(c)))
+                        .collect::<Vec<_>>()
+                        .join(", ");
+                    format!("Literal[{union}]")
+                }
+            } else {
+                "str".to_string()
+            };
+
+            if flag.var {
+                format!("list[{base}]")
+            } else {
+                base
+            }
+        }
+        None => {
+            if flag.var {
+                "list[bool]".to_string()
+            } else {
+                "bool".to_string()
+            }
+        }
+    }
+}
+
+fn config_prop_type(prop: &SpecConfigProp) -> String {
+    match prop.data_type {
+        SpecDataTypes::String => "str".to_string(),
+        SpecDataTypes::Integer => "int".to_string(),
+        SpecDataTypes::Float => "float".to_string(),
+        SpecDataTypes::Boolean => "bool".to_string(),
+        SpecDataTypes::Null => "object".to_string(),
+    }
+}
+
+fn flag_property_name_py(flag: &SpecFlag) -> String {
+    // Python uses snake_case for attributes
+    if let Some(long) = flag.long.first() {
+        return sanitize_py_ident(&heck::AsSnakeCase(long).to_string());
+    }
+    if let Some(short) = flag.short.first() {
+        return short.to_string();
+    }
+    sanitize_py_ident(&flag.name)
+}
+
+fn sanitize_py_ident(name: &str) -> String {
+    let snake = heck::AsSnakeCase(name).to_string();
+    match snake.as_str() {
+        "class" | "def" | "return" | "import" | "from" | "global" | "lambda" | "pass" | "raise"
+        | "with" | "yield" | "del" | "try" | "except" | "finally" | "while" | "for" | "if"
+        | "elif" | "else" | "and" | "or" | "not" | "in" | "is" | "as" | "break" | "continue"
+        | "assert" | "type" | "input" | "id" | "list" | "dict" | "set" | "print" | "range"
+        | "format" | "help" | "vars" | "dir" | "exec" | "exit" | "quit" | "bool" | "int"
+        | "str" | "float" | "bytes" | "object" | "super" | "property" | "static" | "true"
+        | "false" | "none" => format!("_{snake}"),
+        _ => snake,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// client.py
+// ---------------------------------------------------------------------------
+
+fn render_client(spec: &Spec, package_name: &str, source_file: &Option<String>) -> String {
+    let mut w = CodeWriter::with_indent("    ");
+
+    w.line(&generated_header("#", source_file));
+    w.line("from __future__ import annotations");
+    w.line("from typing import Optional");
+    w.line("from .runtime import CliResult, CliRunner");
+
+    // collect imports from types
+    let choice_types = collect_choice_types(&spec.cmd);
+    let type_imports = collect_type_imports(&spec.cmd, package_name, &choice_types);
+    let has_global_flags = spec.cmd.flags.iter().any(|f| f.global && !f.hide);
+    let mut all_imports = type_imports;
+    if has_global_flags {
+        all_imports.push("GlobalFlags".to_string());
+    }
+    all_imports.sort();
+    all_imports.dedup();
+    if !all_imports.is_empty() {
+        w.line(&format!("from .types import {}", all_imports.join(", ")));
+    }
+
+    w.line("");
+
+    let global_flags: Vec<&SpecFlag> = spec
+        .cmd
+        .flags
+        .iter()
+        .filter(|f| f.global && !f.hide)
+        .collect();
+
+    let class_name = AsPascalCase(package_name).to_string();
+    render_class(
+        &spec.cmd,
+        &class_name,
+        true,
+        &global_flags,
+        &spec.bin,
+        &mut w,
+    );
+
+    w.finish()
+}
+
+fn render_class(
+    cmd: &SpecCommand,
+    class_name: &str,
+    is_root: bool,
+    global_flags: &[&SpecFlag],
+    bin_name: &str,
+    w: &mut CodeWriter,
+) {
+    let visible_subcmds: Vec<_> = cmd.subcommands.iter().filter(|(_, c)| !c.hide).collect();
+
+    let visible_args: Vec<&SpecArg> = cmd.args.iter().filter(|a| !a.hide).collect();
+    let visible_flags: Vec<&SpecFlag> = cmd.flags.iter().filter(|f| !f.hide).collect();
+    let has_args = !visible_args.is_empty();
+    let has_flags = !visible_flags.is_empty() || !global_flags.is_empty();
+
+    // docstring on class
+    let mut class_doc = Vec::new();
+    if let Some(help) = &cmd.help {
+        class_doc.push(help.clone());
+    } else if let Some(about) = &cmd.help_long {
+        class_doc.push(about.clone());
+    }
+    if let Some(deprecated) = &cmd.deprecated {
+        class_doc.push(format!("DEPRECATED: {deprecated}"));
+    }
+    if !cmd.aliases.is_empty() {
+        class_doc.push(format!("Aliases: {}", cmd.aliases.join(", ")));
+    }
+
+    w.line(&format!("class {class_name}:"));
+    w.indent();
+
+    if !class_doc.is_empty() {
+        w.line(&format!(
+            "\"\"\"{}\"\"\"",
+            escape_py_docstring(&class_doc.join(". "))
+        ));
+    }
+
+    // constructor
+    if is_root {
+        w.line(&format!(
+            "def __init__(self, bin_path: str = \"{}\") -> None:",
+            escape_py_string(bin_name)
+        ));
+    } else {
+        w.line("def __init__(self, runner: CliRunner) -> None:");
+    }
+    w.indent();
+    if is_root {
+        w.line("self._runner = CliRunner(bin_path)");
+    } else {
+        w.line("self._runner = runner");
+    }
+    for (name, _) in &visible_subcmds {
+        let sub_class = AsPascalCase(name).to_string();
+        let prop = sanitize_py_ident(name);
+        w.line(&format!("self.{prop} = {sub_class}(self._runner)"));
+    }
+    w.dedent();
+
+    // exec method — build signature with four explicit arms to avoid double comma
+    let flags_type = if !global_flags.is_empty() && !visible_flags.is_empty() {
+        format!("{class_name}Flags")
+    } else if !global_flags.is_empty() && visible_flags.is_empty() {
+        "GlobalFlags".to_string()
+    } else if !visible_flags.is_empty() {
+        format!("{class_name}Flags")
+    } else {
+        String::new()
+    };
+    let sig = if has_args && !flags_type.is_empty() {
+        format!("def exec(self, args: {class_name}Args, flags: Optional[{flags_type}] = None) -> CliResult:")
+    } else if has_args {
+        format!("def exec(self, args: {class_name}Args) -> CliResult:")
+    } else if !flags_type.is_empty() {
+        format!("def exec(self, flags: Optional[{flags_type}] = None) -> CliResult:")
+    } else {
+        "def exec(self) -> CliResult:".to_string()
+    };
+
+    // docstring on exec
+    let mut exec_doc = Vec::new();
+    if !cmd.usage.is_empty() {
+        exec_doc.push(cmd.usage.clone());
+    }
+    for example in &cmd.examples {
+        let label = example.header.as_deref().unwrap_or("Example");
+        exec_doc.push(format!("{label}: {code}", code = example.code));
+    }
+
+    w.line("");
+    if !exec_doc.is_empty() {
+        w.line(&sig);
+        w.indent();
+        if exec_doc.len() == 1 {
+            w.line(&format!(
+                "\"\"\"{}\"\"\"",
+                escape_py_docstring(&exec_doc[0])
+            ));
+        } else {
+            w.line(&format!("\"\"\"{}", escape_py_docstring(&exec_doc[0])));
+            for part in exec_doc.iter().skip(1) {
+                w.line(&escape_py_docstring(part));
+            }
+            w.line("\"\"\"");
+        }
+    } else {
+        w.line(&sig);
+        w.indent();
+    }
+
+    let path: String = cmd
+        .full_cmd
+        .iter()
+        .map(|s| format!("\"{}\"", escape_py_string(s)))
+        .collect::<Vec<_>>()
+        .join(", ");
+    w.line(&format!("cmd_args: list[str] = [{path}]"));
+
+    if has_args {
+        let has_required_double_dash = visible_args
+            .iter()
+            .any(|a| matches!(a.double_dash, SpecDoubleDashChoices::Required));
+        let has_automatic_double_dash = visible_args
+            .iter()
+            .any(|a| matches!(a.double_dash, SpecDoubleDashChoices::Automatic));
+
+        // Args before `--`: all args without double_dash=required
+        for arg in &visible_args {
+            if matches!(arg.double_dash, SpecDoubleDashChoices::Required) {
+                continue;
+            }
+            let ident = sanitize_py_ident(&arg.name);
+            if arg.var {
+                w.line(&format!(
+                    "if args.{ident} is not None: cmd_args.extend(args.{ident})"
+                ));
+            } else {
+                w.line(&format!(
+                    "if args.{ident} is not None: cmd_args.append(str(args.{ident}))"
+                ));
+            }
+        }
+
+        if has_required_double_dash {
+            w.line("cmd_args.append(\"--\")");
+            // Args after `--`: only double_dash=required args
+            for arg in &visible_args {
+                if !matches!(arg.double_dash, SpecDoubleDashChoices::Required) {
+                    continue;
+                }
+                let ident = sanitize_py_ident(&arg.name);
+                if arg.var {
+                    w.line(&format!(
+                        "if args.{ident} is not None: cmd_args.extend(args.{ident})"
+                    ));
+                } else {
+                    w.line(&format!(
+                        "if args.{ident} is not None: cmd_args.append(str(args.{ident}))"
+                    ));
+                }
+            }
+        } else if has_automatic_double_dash {
+            w.line("# double_dash=automatic: \"--\" is implied after the first positional arg");
+        }
+    }
+
+    if has_flags {
+        w.line("flag_args = self._build_flag_args(flags)");
+        w.line("return self._runner.run(cmd_args + flag_args)");
+    } else {
+        w.line("return self._runner.run(cmd_args)");
+    }
+
+    w.dedent();
+
+    // _build_flag_args
+    if has_flags {
+        w.line("");
+        w.line(&format!(
+            "def _build_flag_args(self, flags: Optional[{flags_type}]) -> list[str]:"
+        ));
+        w.indent();
+        w.line("result: list[str] = []");
+        w.line("if flags is None: return result");
+
+        for flag in global_flags {
+            render_flag_build_py(flag, w);
+        }
+        for flag in &visible_flags {
+            // skip global flags already rendered above
+            if !global_flags.iter().any(|gf| gf.name == flag.name) {
+                render_flag_build_py(flag, w);
+            }
+        }
+
+        w.line("return result");
+        w.dedent();
+    }
+
+    // alias properties for subcommand aliases
+    for (name, subcmd) in &visible_subcmds {
+        for alias in &subcmd.aliases {
+            let alias_prop = sanitize_py_ident(alias);
+            let target_prop = sanitize_py_ident(name);
+            let sub_class = AsPascalCase(name).to_string();
+            w.line("");
+            w.line("@property");
+            w.line(&format!("def {alias_prop}(self) -> {sub_class}:"));
+            w.indent();
+            w.line(&format!(
+                "\"\"\"Alias for {}.\"\"\"",
+                escape_py_docstring(name)
+            ));
+            w.line(&format!("return self.{target_prop}"));
+            w.dedent();
+        }
+    }
+
+    w.dedent(); // end class
+
+    // render subcommand classes
+    for (name, subcmd) in &visible_subcmds {
+        w.line("");
+        let sub_class = AsPascalCase(name).to_string();
+        render_class(subcmd, &sub_class, false, global_flags, bin_name, w);
+    }
+}
+
+fn render_flag_build_py(flag: &SpecFlag, w: &mut CodeWriter) {
+    let prop_name = flag_property_name_py(flag);
+    let flag_arg_name = if let Some(long) = flag.long.first() {
+        format!("--{}", escape_py_string(long))
+    } else if let Some(short) = flag.short.first() {
+        format!("-{short}")
+    } else {
+        format!("--{}", escape_py_string(&flag.name))
+    };
+
+    if flag.arg.is_some() {
+        if flag.var {
+            w.line(&format!("if flags.{prop_name} is not None:"));
+            w.indent();
+            w.line(&format!(
+                "for v in flags.{prop_name}: result.extend([\"{flag_arg_name}\", str(v)])"
+            ));
+            w.dedent();
+        } else {
+            w.line(&format!(
+                "if flags.{prop_name} is not None: result.extend([\"{flag_arg_name}\", str(flags.{prop_name})])"
+            ));
+        }
+    } else if flag.count {
+        w.line(&format!(
+            "if flags.{prop_name} is not None and flags.{prop_name} > 0: result.extend([\"{flag_arg_name}\"] * flags.{prop_name})"
+        ));
+    } else if flag.var {
+        w.line(&format!("if flags.{prop_name} is not None:"));
+        w.indent();
+        w.line(&format!("for v in flags.{prop_name}:"));
+        w.indent();
+        w.line(&format!("if v: result.append(\"{flag_arg_name}\")"));
+        w.dedent();
+        w.dedent();
+    } else {
+        w.line(&format!(
+            "if flags.{prop_name}: result.append(\"{flag_arg_name}\")"
+        ));
+        if let Some(negate) = &flag.negate {
+            w.line(&format!(
+                "elif flags.{prop_name} is False: result.append(\"{}\")",
+                escape_py_string(negate)
+            ));
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use crate::sdk::{SdkLanguage, SdkOptions};
+    use crate::test::SPEC_KITCHEN_SINK;
+    use crate::Spec;
+
+    fn make_opts() -> SdkOptions {
+        SdkOptions {
+            language: SdkLanguage::Python,
+            package_name: None,
+            source_file: Some("test.usage.kdl".to_string()),
+        }
+    }
+
+    fn get_file<'a>(output: &'a crate::sdk::SdkOutput, name: &str) -> &'a str {
+        output
+            .files
+            .iter()
+            .find(|f| f.path.to_str() == Some(name))
+            .unwrap_or_else(|| panic!("{name} should exist"))
+            .content
+            .as_str()
+    }
+
+    #[test]
+    fn test_python_types() {
+        let output = crate::sdk::generate(&SPEC_KITCHEN_SINK, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "types.py"));
+    }
+
+    #[test]
+    fn test_python_client() {
+        let output = crate::sdk::generate(&SPEC_KITCHEN_SINK, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.py"));
+    }
+
+    #[test]
+    fn test_python_runtime() {
+        let output = crate::sdk::generate(&SPEC_KITCHEN_SINK, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "runtime.py"));
+    }
+
+    #[test]
+    fn test_python_init() {
+        let output = crate::sdk::generate(&SPEC_KITCHEN_SINK, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "__init__.py"));
+    }
+
+    fn full_feature_spec() -> Spec {
+        r##"
+            bin "mytool"
+            name "mytool"
+            version "1.2.3"
+            about "A powerful CLI tool"
+            author "Jane Doe"
+
+            flag "-v --verbose" help="Verbosity level" count=#true global=#true
+            flag "-C --config <path>" help="Config file path" global=#true env="MYTOOL_CONFIG"
+            flag "--dry-run" help="Show what would be done" negate="--no-dry-run"
+
+            arg "input" help="Input file" required=#true
+            arg "extra" var=#true help="Extra files"
+
+            cmd "build" help="Build the project" deprecated="Use compile instead" {
+                alias "b"
+                arg "target" help="Build target" {
+                    choices "debug" "release"
+                }
+                arg "output" help="Output directory" double_dash="required"
+                flag "-j --jobs <n>" help="Parallel jobs" var=#true
+                flag "--release" help="Build in release mode"
+            }
+
+            cmd "deploy" help="Deploy the project" {
+                arg "env" help="Target environment" {
+                    choices "staging" "production"
+                }
+                arg "tags" var=#true help="Deployment tags" var_min=1 var_max=5
+                flag "-f --force" help="Force deploy" deprecated="Use --confirm instead"
+                flag "--confirm" help="Confirm deployment"
+            }
+        "##
+        .parse()
+        .unwrap()
+    }
+
+    #[test]
+    fn test_python_full_feature_types() {
+        let spec = full_feature_spec();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "types.py"));
+    }
+
+    #[test]
+    fn test_python_full_feature_client() {
+        let spec = full_feature_spec();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.py"));
+    }
+
+    #[test]
+    fn test_python_hyphenated_subcommands() {
+        let spec: Spec = r##"
+            bin "cli"
+            cmd "add-remote" help="Add a remote" {
+                arg "name"
+                arg "url"
+            }
+            cmd "remove-remote" help="Remove a remote" {
+                arg "name"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.py"));
+    }
+
+    #[test]
+    fn test_python_minimal() {
+        let spec: Spec = r##"
+            bin "hello"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.py"));
+    }
+
+    /// Flags-only subcommand (no positional args) — tests exec signature without double comma.
+    #[test]
+    fn test_python_flags_only_subcommand() {
+        let spec: Spec = r##"
+            bin "app"
+            cmd "status" help="Show status" {
+                flag "--verbose" help="Show detailed status"
+                flag "--json" help="Output as JSON"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        assert!(!client.contains("def exec(self, ,"));
+        assert!(
+            client.contains("def exec(self, flags: Optional[StatusFlags] = None) -> CliResult:")
+        );
+        insta::assert_snapshot!(client);
+    }
+
+    /// Choice type collision: same arg name with different choices in different subcommands.
+    #[test]
+    fn test_python_choice_collision() {
+        let spec: Spec = r##"
+            bin "tool"
+            cmd "build" help="Build" {
+                arg "env" help="Build environment" {
+                    choices "debug" "release"
+                }
+            }
+            cmd "deploy" help="Deploy" {
+                arg "env" help="Deploy environment" {
+                    choices "staging" "production"
+                }
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        // Must have separate choice types due to collision
+        assert!(types.contains("BuildEnvChoice"));
+        assert!(types.contains("DeployEnvChoice"));
+        assert!(types.contains(r#""debug""#));
+        assert!(types.contains(r#""staging""#));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Args with default values — tests that defaults are preserved, not dropped to None.
+    #[test]
+    fn test_python_arg_defaults() {
+        let spec: Spec = r##"
+            bin "runner"
+            arg "mode" default="fast" help="Run mode"
+            arg "output" help="Output path" required=#true
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains(r#"mode: Optional[str] = "fast""#));
+        assert!(types.contains("output: str"));
+        // required arg must come before optional
+        let output_pos = types.find("output: str").unwrap();
+        let mode_pos = types.find(r#"mode: Optional[str] = "fast""#).unwrap();
+        assert!(
+            output_pos < mode_pos,
+            "required arg must precede optional arg"
+        );
+    }
+
+    /// Config props — covers config dataclass and config_prop_type.
+    #[test]
+    fn test_python_config_props() {
+        let spec: Spec = r##"
+            bin "myapp"
+            config {
+                prop "debug" default=#true data_type=boolean help="Enable debug mode"
+                prop "port" default=8080 data_type=integer
+                prop "rate" default="1.5" data_type=float
+                prop "host" data_type=string
+                prop "extra" data_type="null"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("class MyappConfig"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Hidden command, hidden arg/flag — covers early-return and empty dataclass paths.
+    #[test]
+    fn test_python_hidden_command() {
+        let spec: Spec = r##"
+            bin "app"
+            cmd "visible" help="A visible command" {
+                arg "name"
+            }
+            cmd "secret" hide=#true help="Hidden command" {
+                arg "name"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("VisibleArgs"));
+        assert!(!types.contains("SecretArgs"));
+    }
+
+    /// Flag edge cases: short-only, aliases, deprecated, count+default, required flag,
+    /// repeatable boolean flag, non-bool value flag with default.
+    #[test]
+    fn test_python_flag_edge_cases() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "-v" help="Short-only flag"
+            flag "--type" help="Reserved keyword" deprecated="Use --kind"
+            flag "--level" count=#true default="2" help="Count flag with default"
+            flag "--format <fmt>" default="json" help="Value flag with default"
+            flag "--confirm" required=#true help="Required flag"
+            flag "--verbose" var=#true help="Repeatable boolean flag"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        insta::assert_snapshot!(types);
+        let client = get_file(&output, "client.py");
+        // short-only flag build
+        assert!(client.contains(r#""-v""#));
+        // repeatable boolean flag build
+        assert!(client.contains("for v in flags.verbose:"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// double_dash=automatic, examples in exec doc, global flags with flags-only subcommand.
+    #[test]
+    fn test_python_exec_edge_cases() {
+        let spec: Spec = r##"
+            bin "runner"
+            flag "-v --verbose" global=#true help="Verbosity"
+            arg "input" help="Input file"
+            arg "extra" double_dash="automatic" var=#true help="Extra files"
+            cmd "run" help="Run a task" {
+                example "runner run hello" header="Basic run"
+                arg "task" help="Task to run" double_dash="automatic"
+            }
+            cmd "info" help="Show info" {}
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        assert!(client.contains("double_dash=automatic"));
+        assert!(client.contains("Basic run: runner run hello"));
+        // "info" has no own flags, only global flags => GlobalFlags type
+        assert!(client.contains("flags: Optional[GlobalFlags] = None"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Optional arg without default and empty flags dataclass.
+    #[test]
+    fn test_python_optional_arg_empty_flags() {
+        let spec: Spec = r##"
+            bin "app"
+            arg "[name]" help="Optional arg without default"
+            cmd "check" help="Check something" {
+                arg "target" required=#true help="Required arg"
+                arg "mode" default="quick" help="Optional arg with default"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        // optional arg without default should have = None
+        assert!(types.contains("name: Optional[str] = None"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Deeply nested subcommands — 3+ levels.
+    #[test]
+    fn test_python_deep_nesting() {
+        let spec: Spec = r##"
+            bin "app"
+            cmd "db" help="Database operations" {
+                cmd "migration" help="Migration management" {
+                    cmd "create" help="Create a new migration" {
+                        arg "name"
+                        flag "--template <t>" help="Migration template"
+                    }
+                    cmd "run" help="Run pending migrations" {
+                        flag "--step <n>" help="Number of migrations to run"
+                    }
+                }
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        // deeply nested class must exist
+        assert!(client.contains("class Db:"));
+        assert!(client.contains("class Migration:"));
+        assert!(client.contains("class Create:"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Test package_name override.
+    #[test]
+    fn test_python_package_name_override() {
+        let spec: Spec = r##"
+            bin "original-cli"
+        "##
+        .parse()
+        .unwrap();
+        let opts = SdkOptions {
+            language: SdkLanguage::Python,
+            package_name: Some("my_custom_sdk".to_string()),
+            source_file: None,
+        };
+        let output = crate::sdk::generate(&spec, &opts);
+        let init = get_file(&output, "__init__.py");
+        assert!(init.contains("MyCustomSdk"));
+        insta::assert_snapshot!(init);
+    }
+
+    /// Global flags with flags-only subcommand — covers GlobalFlags type branch.
+    #[test]
+    fn test_python_global_flags_flags_only() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "-v --verbose" global=#true help="Verbosity"
+            cmd "status" help="Show status" {
+                flag "--json" help="JSON output"
+            }
+            cmd "info" help="Show info" {}
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        // "info" subcommand has no own flags, only global flags => GlobalFlags type
+        assert!(client.contains("Optional[GlobalFlags]"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Flag with choices — flag arg with choices renders correct type.
+    #[test]
+    fn test_python_flag_with_choices() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "--shell <shell>" help="Shell type" {
+                choices "bash" "zsh" "fish"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("Literal[\"bash\", \"zsh\", \"fish\"]"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Flag with env annotation — env variable appears in comment.
+    #[test]
+    fn test_python_flag_with_env() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "--config <path>" help="Config file" env="APP_CONFIG"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("Env: APP_CONFIG"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Hidden flag excluded from types and client.
+    #[test]
+    fn test_python_flag_hide() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "--verbose" help="Verbosity"
+            flag "--debug" hide=#true help="Hidden debug flag"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("verbose"));
+        assert!(!types.contains("debug"));
+    }
+
+    /// Negate flag rendered in client build method.
+    #[test]
+    fn test_python_negate_flag_build() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "--dry-run" help="Dry run" negate="--no-dry-run"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        assert!(client.contains("--dry-run"));
+        assert!(client.contains("--no-dry-run"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Count flag rendered in client build method.
+    #[test]
+    fn test_python_count_flag_build() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "-v --verbose" count=#true help="Verbosity level"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        assert!(client.contains(r#""--verbose""#));
+        assert!(client.contains("flags.verbose"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Repeatable value flag with default — covers var + arg + default in client build.
+    #[test]
+    fn test_python_var_value_flag_with_default() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "--tag <t>" var=#true default="latest" help="Tags"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains(r#"list[str]"#));
+        assert!(types.contains(r#"default: latest"#));
+        let client = get_file(&output, "client.py");
+        assert!(client.contains("for v in flags.tag:"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Flag with multiple long aliases — `-f --format --fmt <fmt>`.
+    #[test]
+    fn test_python_multiple_aliases() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "-f --format --fmt <fmt>" help="Output format"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("Aliases: fmt"));
+        let client = get_file(&output, "client.py");
+        // should use first long for the flag argument name
+        assert!(client.contains("--format"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Boolean flag with default=#false — covers the "= False" branch.
+    #[test]
+    fn test_python_boolean_flag_default_false() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "--no-cache" default=#false help="Disable cache"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("no_cache: bool = False"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Boolean config prop with default=#false — covers the "= False" branch.
+    #[test]
+    fn test_python_config_boolean_default_false() {
+        let spec: Spec = r##"
+            bin "app"
+            config {
+                prop "verbose" default=#false data_type=boolean help="Verbose output"
+                prop "dry_run" default=#true data_type=boolean help="Dry run mode"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("verbose: bool = False"));
+        assert!(types.contains("dry_run: bool = True"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// String config prop with default — covers String/Null match arm with default.
+    #[test]
+    fn test_python_config_string_with_default() {
+        let spec: Spec = r##"
+            bin "app"
+            config {
+                prop "host" default="localhost" data_type=string help="Server host"
+                prop "name" default="myapp" data_type=string
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains(r#"host: str = "localhost""#));
+        assert!(types.contains(r#"name: str = "myapp""#));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Config with all props having defaults — tests Default derive on config dataclass.
+    #[test]
+    fn test_python_config_all_optional() {
+        let spec: Spec = r##"
+            bin "app"
+            config {
+                prop "debug" default=#true data_type=boolean
+                prop "port" default=8080 data_type=integer
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("class AppConfig:"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Optional variadic arg — covers the optional + var branch in client rendering.
+    #[test]
+    fn test_python_optional_variadic_arg() {
+        let spec: Spec = r##"
+            bin "tool"
+            arg "[files]" var=#true help="Input files"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("list[str]"));
+        let client = get_file(&output, "client.py");
+        // optional variadic arg should use extend with None guard
+        assert!(client.contains("if args.files is not None: cmd_args.extend(args.files)"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Example without lang attribute — tests single-line exec doc path.
+    #[test]
+    fn test_python_example_without_lang() {
+        let spec: Spec = r##"
+            bin "app"
+            cmd "greet" help="Greet someone" {
+                example "app greet hello"
+                arg "name" help="Name to greet"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        assert!(client.contains("app greet hello"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Required flag without default — tests non-optional flag type rendering.
+    #[test]
+    fn test_python_required_flag_type() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "--token <t>" required=#true help="Auth token"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        // required flag without default should NOT be Optional
+        assert!(types.contains("token: str"));
+        assert!(!types.contains("token: Optional[str]"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Global repeatable flags — covers flag_ts_simple var branches.
+    #[test]
+    fn test_python_global_repeatable_flags() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "-v --verbose" global=#true var=#true help="Repeatable verbose"
+            flag "--tag <t>" global=#true var=#true help="Repeatable tag"
+            cmd "run" help="Run" {
+                arg "target"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        // GlobalFlags should have list[bool] and list[str] types
+        assert!(types.contains("list[bool]"));
+        assert!(types.contains("list[str]"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Client edge cases: double_dash=automatic, examples, global flags, repeatable boolean flag.
+    #[test]
+    fn test_python_client_edge_cases() {
+        let spec: Spec = r##"
+            bin "runner"
+            flag "-v --verbose" global=#true help="Verbosity"
+            flag "--debug" var=#true help="Repeatable boolean flag"
+            arg "input" help="Input file"
+            arg "extra" double_dash="automatic" var=#true help="Extra files"
+            cmd "run" help="Run a task" {
+                example "runner run hello" header="Basic run" lang="bash"
+                arg "task" help="Task to run" double_dash="automatic"
+            }
+            cmd "info" help="Show info" {}
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        assert!(client.contains("double_dash=automatic"));
+        assert!(client.contains("Basic run: runner run hello"));
+        // GlobalFlags type for info subcommand
+        assert!(client.contains("Optional[GlobalFlags]"));
+        // repeatable boolean flag
+        assert!(client.contains("for v in flags.debug:"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Config and flag edge cases — config with various data types, env, deprecated, aliases.
+    #[test]
+    fn test_python_config_and_flag_edge_cases() {
+        let spec: Spec = r##"
+            bin "myapp"
+            config {
+                prop "debug" default=#true data_type=boolean help="Enable debug mode"
+                prop "port" default=8080 data_type=integer
+                prop "rate" default="1.5" data_type=float
+                prop "host" data_type=string
+            }
+            arg "input" help="Input file" env="MYAPP_INPUT"
+            flag "--type" help="Reserved keyword" deprecated="Use --kind"
+            flag "-f --format --fmt <fmt>" help="Flag with short and long alias"
+            flag "-v" help="Short-only flag"
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.py");
+        assert!(types.contains("MyappConfig"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// double_dash=automatic — covers arg ordering and separator insertion.
+    #[test]
+    fn test_python_double_dash_automatic() {
+        let spec: Spec = r##"
+            bin "runner"
+            arg "input" help="Input file"
+            arg "extra" double_dash="automatic" var=#true help="Extra files"
+            flag "--verbose" var=#true help="Repeatable boolean flag"
+            cmd "run" help="Run a task" {
+                example "runner run hello" header="Basic run"
+                arg "task" help="Task to run" double_dash="automatic"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = crate::sdk::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.py");
+        assert!(client.contains("double_dash=automatic"));
+        insta::assert_snapshot!(client);
+    }
+}
diff --git a/lib/src/sdk/python/runtime.rs b/lib/src/sdk/python/runtime.rs
new file mode 100644
index 00000000..2641ec86
--- /dev/null
+++ b/lib/src/sdk/python/runtime.rs
@@ -0,0 +1,36 @@
+pub const RUNTIME_PY: &str = r#"# Runtime module for usage-generated SDK clients. Do not edit manually.
+from __future__ import annotations
+
+import subprocess
+
+
+class CliResult:
+    """Result of a CLI invocation."""
+
+    def __init__(self, stdout: str, stderr: str, exit_code: int) -> None:
+        self.stdout = stdout
+        self.stderr = stderr
+        self.exit_code = exit_code
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+class CliRunner:
+    """Runs a CLI binary via subprocess."""
+
+    def __init__(self, bin_path: str) -> None:
+        self.bin_path = bin_path
+
+    def run(self, args: list[str]) -> CliResult:
+        try:
+            result = subprocess.run(
+                [self.bin_path, *args],
+                capture_output=True,
+                text=True,
+            )
+            return CliResult(result.stdout, result.stderr, result.returncode)
+        except FileNotFoundError:
+            raise RuntimeError(f"CLI binary not found: {self.bin_path}")
+"#;
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_boolean_flag_default_false.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_boolean_flag_default_false.snap
new file mode 100644
index 00000000..f97b7344
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_boolean_flag_default_false.snap
@@ -0,0 +1,15 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class AppFlags:
+    # Disable cache
+    no_cache: bool = False
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_choice_collision.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_choice_collision.snap
new file mode 100644
index 00000000..556aea95
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_choice_collision.snap
@@ -0,0 +1,24 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+BuildEnvChoice = Literal["debug", "release"]
+DeployEnvChoice = Literal["staging", "production"]
+
+
+@dataclass
+class BuildArgs:
+    # Build environment
+    env: BuildEnvChoice
+
+
+@dataclass
+class DeployArgs:
+    # Deploy environment
+    env: DeployEnvChoice
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_client.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_client.snap
new file mode 100644
index 00000000..6e28e99a
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_client.snap
@@ -0,0 +1,68 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: "get_file(&output, \"client.py\")"
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import Arg2Choice, InstallArgs, InstallFlags, MycliArgs, MycliFlags, ShellChoice
+
+class Mycli:
+    def __init__(self, bin_path: str = "mycli") -> None:
+        self._runner = CliRunner(bin_path)
+        self.plugin = Plugin(self._runner)
+
+    def exec(self, args: MycliArgs, flags: Optional[MycliFlags] = None) -> CliResult:
+        """[FLAGS] <ARGS>… <SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        if args.arg1 is not None: cmd_args.append(str(args.arg1))
+        if args.arg2 is not None: cmd_args.append(str(args.arg2))
+        if args.arg3 is not None: cmd_args.append(str(args.arg3))
+        if args.argrest is not None: cmd_args.extend(args.argrest)
+        if args.with_default is not None: cmd_args.append(str(args.with_default))
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[MycliFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.flag1: result.append("--flag1")
+        if flags.flag2: result.append("--flag2")
+        if flags.flag3: result.append("--flag3")
+        elif flags.flag3 is False: result.append("--no-flag3")
+        if flags.with_default: result.append("--with-default")
+        if flags.shell is not None: result.extend(["--shell", str(flags.shell)])
+        return result
+
+class Plugin:
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+        self.install = Install(self._runner)
+
+    def exec(self) -> CliResult:
+        """plugin <SUBCOMMAND>"""
+        cmd_args: list[str] = ["plugin"]
+        return self._runner.run(cmd_args)
+
+class Install:
+    """install a plugin"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: InstallArgs, flags: Optional[InstallFlags] = None) -> CliResult:
+        """plugin install [FLAGS] <plugin> <version>"""
+        cmd_args: list[str] = ["plugin", "install"]
+        if args.plugin is not None: cmd_args.append(str(args.plugin))
+        if args.version is not None: cmd_args.append(str(args.version))
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[InstallFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags._global: result.append("--global")
+        if flags._dir is not None: result.extend(["--dir", str(flags._dir)])
+        if flags.force: result.append("--force")
+        elif flags.force is False: result.append("--no-force")
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_client_edge_cases.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_client_edge_cases.snap
new file mode 100644
index 00000000..2fc18351
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_client_edge_cases.snap
@@ -0,0 +1,71 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import GlobalFlags, RunArgs, RunnerArgs, RunnerFlags
+
+class Runner:
+    def __init__(self, bin_path: str = "runner") -> None:
+        self._runner = CliRunner(bin_path)
+        self.run = Run(self._runner)
+        self.info = Info(self._runner)
+
+    def exec(self, args: RunnerArgs, flags: Optional[RunnerFlags] = None) -> CliResult:
+        """[-v --verbose] [--debug…] <input> <extra>… <SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        if args._input is not None: cmd_args.append(str(args._input))
+        if args.extra is not None: cmd_args.extend(args.extra)
+        # double_dash=automatic: "--" is implied after the first positional arg
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[RunnerFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        if flags.debug is not None:
+            for v in flags.debug:
+                if v: result.append("--debug")
+        return result
+
+class Run:
+    """Run a task"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: RunArgs, flags: Optional[GlobalFlags] = None) -> CliResult:
+        """run <task>
+        Basic run: runner run hello
+        """
+        cmd_args: list[str] = ["run"]
+        if args.task is not None: cmd_args.append(str(args.task))
+        # double_dash=automatic: "--" is implied after the first positional arg
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[GlobalFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        return result
+
+class Info:
+    """Show info"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, flags: Optional[GlobalFlags] = None) -> CliResult:
+        """info"""
+        cmd_args: list[str] = ["info"]
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[GlobalFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_all_optional.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_all_optional.snap
new file mode 100644
index 00000000..265f3ef2
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_all_optional.snap
@@ -0,0 +1,15 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class AppConfig:
+    debug: bool = True
+    port: int = 8080
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_and_flag_edge_cases.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_and_flag_edge_cases.snap
new file mode 100644
index 00000000..8b58c89f
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_and_flag_edge_cases.snap
@@ -0,0 +1,34 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class MyappArgs:
+    # Input file
+    _input: str
+
+
+@dataclass
+class MyappFlags:
+    # Reserved keyword. Deprecated: Use --kind
+    _type: Optional[bool] = None
+    # Flag with short and long alias. Aliases: fmt. Short: -f
+    _format: Optional[str] = None
+    # Short-only flag. Short: -v
+    v: Optional[bool] = None
+
+
+@dataclass
+class MyappConfig:
+    host: str
+    # Enable debug mode
+    debug: bool = True
+    port: int = 8080
+    rate: float = 1.5
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_boolean_default_false.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_boolean_default_false.snap
new file mode 100644
index 00000000..18e6a6f7
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_boolean_default_false.snap
@@ -0,0 +1,17 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class AppConfig:
+    # Dry run mode
+    dry_run: bool = True
+    # Verbose output
+    verbose: bool = False
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_props.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_props.snap
new file mode 100644
index 00000000..5d475470
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_props.snap
@@ -0,0 +1,19 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class MyappConfig:
+    extra: object
+    host: str
+    # Enable debug mode
+    debug: bool = True
+    port: int = 8080
+    rate: float = 1.5
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_string_with_default.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_string_with_default.snap
new file mode 100644
index 00000000..70a75509
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_config_string_with_default.snap
@@ -0,0 +1,16 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class AppConfig:
+    # Server host
+    host: str = "localhost"
+    name: str = "myapp"
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_count_flag_build.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_count_flag_build.snap
new file mode 100644
index 00000000..0b0c6c34
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_count_flag_build.snap
@@ -0,0 +1,25 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import AppFlags
+
+class App:
+    def __init__(self, bin_path: str = "app") -> None:
+        self._runner = CliRunner(bin_path)
+
+    def exec(self, flags: Optional[AppFlags] = None) -> CliResult:
+        """[-v --verbose]"""
+        cmd_args: list[str] = []
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[AppFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose is not None and flags.verbose > 0: result.extend(["--verbose"] * flags.verbose)
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_deep_nesting.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_deep_nesting.snap
new file mode 100644
index 00000000..de8413b7
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_deep_nesting.snap
@@ -0,0 +1,77 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import CreateArgs, CreateFlags, RunFlags
+
+class App:
+    def __init__(self, bin_path: str = "app") -> None:
+        self._runner = CliRunner(bin_path)
+        self.db = Db(self._runner)
+
+    def exec(self) -> CliResult:
+        """<SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        return self._runner.run(cmd_args)
+
+class Db:
+    """Database operations"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+        self.migration = Migration(self._runner)
+
+    def exec(self) -> CliResult:
+        """db <SUBCOMMAND>"""
+        cmd_args: list[str] = ["db"]
+        return self._runner.run(cmd_args)
+
+class Migration:
+    """Migration management"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+        self.create = Create(self._runner)
+        self.run = Run(self._runner)
+
+    def exec(self) -> CliResult:
+        """db migration <SUBCOMMAND>"""
+        cmd_args: list[str] = ["db", "migration"]
+        return self._runner.run(cmd_args)
+
+class Create:
+    """Create a new migration"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: CreateArgs, flags: Optional[CreateFlags] = None) -> CliResult:
+        """db migration create [--template <t>] <name>"""
+        cmd_args: list[str] = ["db", "migration", "create"]
+        if args.name is not None: cmd_args.append(str(args.name))
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[CreateFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.template is not None: result.extend(["--template", str(flags.template)])
+        return result
+
+class Run:
+    """Run pending migrations"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, flags: Optional[RunFlags] = None) -> CliResult:
+        """db migration run [--step <n>]"""
+        cmd_args: list[str] = ["db", "migration", "run"]
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[RunFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.step is not None: result.extend(["--step", str(flags.step)])
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_double_dash_automatic.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_double_dash_automatic.snap
new file mode 100644
index 00000000..9ee67c47
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_double_dash_automatic.snap
@@ -0,0 +1,45 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import RunArgs, RunnerArgs, RunnerFlags
+
+class Runner:
+    def __init__(self, bin_path: str = "runner") -> None:
+        self._runner = CliRunner(bin_path)
+        self.run = Run(self._runner)
+
+    def exec(self, args: RunnerArgs, flags: Optional[RunnerFlags] = None) -> CliResult:
+        """[--verbose…] <input> <extra>… <SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        if args._input is not None: cmd_args.append(str(args._input))
+        if args.extra is not None: cmd_args.extend(args.extra)
+        # double_dash=automatic: "--" is implied after the first positional arg
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[RunnerFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose is not None:
+            for v in flags.verbose:
+                if v: result.append("--verbose")
+        return result
+
+class Run:
+    """Run a task"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: RunArgs) -> CliResult:
+        """run <task>
+        Basic run: runner run hello
+        """
+        cmd_args: list[str] = ["run"]
+        if args.task is not None: cmd_args.append(str(args.task))
+        # double_dash=automatic: "--" is implied after the first positional arg
+        return self._runner.run(cmd_args)
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_example_without_lang.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_example_without_lang.snap
new file mode 100644
index 00000000..76717923
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_example_without_lang.snap
@@ -0,0 +1,32 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import GreetArgs
+
+class App:
+    def __init__(self, bin_path: str = "app") -> None:
+        self._runner = CliRunner(bin_path)
+        self.greet = Greet(self._runner)
+
+    def exec(self) -> CliResult:
+        """<SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        return self._runner.run(cmd_args)
+
+class Greet:
+    """Greet someone"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: GreetArgs) -> CliResult:
+        """greet <name>
+        Example: app greet hello
+        """
+        cmd_args: list[str] = ["greet"]
+        if args.name is not None: cmd_args.append(str(args.name))
+        return self._runner.run(cmd_args)
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_exec_edge_cases.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_exec_edge_cases.snap
new file mode 100644
index 00000000..8c0a20df
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_exec_edge_cases.snap
@@ -0,0 +1,68 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import GlobalFlags, RunArgs, RunnerArgs, RunnerFlags
+
+class Runner:
+    def __init__(self, bin_path: str = "runner") -> None:
+        self._runner = CliRunner(bin_path)
+        self.run = Run(self._runner)
+        self.info = Info(self._runner)
+
+    def exec(self, args: RunnerArgs, flags: Optional[RunnerFlags] = None) -> CliResult:
+        """[-v --verbose] <input> <extra>… <SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        if args._input is not None: cmd_args.append(str(args._input))
+        if args.extra is not None: cmd_args.extend(args.extra)
+        # double_dash=automatic: "--" is implied after the first positional arg
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[RunnerFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        return result
+
+class Run:
+    """Run a task"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: RunArgs, flags: Optional[GlobalFlags] = None) -> CliResult:
+        """run <task>
+        Basic run: runner run hello
+        """
+        cmd_args: list[str] = ["run"]
+        if args.task is not None: cmd_args.append(str(args.task))
+        # double_dash=automatic: "--" is implied after the first positional arg
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[GlobalFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        return result
+
+class Info:
+    """Show info"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, flags: Optional[GlobalFlags] = None) -> CliResult:
+        """info"""
+        cmd_args: list[str] = ["info"]
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[GlobalFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_edge_cases-2.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_edge_cases-2.snap
new file mode 100644
index 00000000..9acb18d4
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_edge_cases-2.snap
@@ -0,0 +1,32 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import ToolFlags
+
+class Tool:
+    def __init__(self, bin_path: str = "tool") -> None:
+        self._runner = CliRunner(bin_path)
+
+    def exec(self, flags: Optional[ToolFlags] = None) -> CliResult:
+        """<FLAGS>"""
+        cmd_args: list[str] = []
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[ToolFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.v: result.append("-v")
+        if flags._type: result.append("--type")
+        if flags.level is not None and flags.level > 0: result.extend(["--level"] * flags.level)
+        if flags._format is not None: result.extend(["--format", str(flags._format)])
+        if flags.confirm: result.append("--confirm")
+        if flags.verbose is not None:
+            for v in flags.verbose:
+                if v: result.append("--verbose")
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_edge_cases.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_edge_cases.snap
new file mode 100644
index 00000000..69bee154
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_edge_cases.snap
@@ -0,0 +1,25 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class ToolFlags:
+    # Required flag
+    confirm: bool
+    # Short-only flag. Short: -v
+    v: Optional[bool] = None
+    # Reserved keyword. Deprecated: Use --kind
+    _type: Optional[bool] = None
+    # Count flag with default
+    level: int = 2
+    # Value flag with default
+    _format: Optional[str] = "json"
+    # Repeatable boolean flag
+    verbose: Optional[list[bool]] = None
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_with_choices.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_with_choices.snap
new file mode 100644
index 00000000..be68b0b4
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_with_choices.snap
@@ -0,0 +1,17 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+ShellChoice = Literal["bash", "zsh", "fish"]
+
+
+@dataclass
+class ToolFlags:
+    # Shell type
+    shell: Optional[ShellChoice] = None
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_with_env.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_with_env.snap
new file mode 100644
index 00000000..6d3f082d
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flag_with_env.snap
@@ -0,0 +1,15 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class AppFlags:
+    # Config file. Env: APP_CONFIG
+    config: Optional[str] = None
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flags_only_subcommand.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flags_only_subcommand.snap
new file mode 100644
index 00000000..62b27e16
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_flags_only_subcommand.snap
@@ -0,0 +1,37 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import StatusFlags
+
+class App:
+    def __init__(self, bin_path: str = "app") -> None:
+        self._runner = CliRunner(bin_path)
+        self.status = Status(self._runner)
+
+    def exec(self) -> CliResult:
+        """<SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        return self._runner.run(cmd_args)
+
+class Status:
+    """Show status"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, flags: Optional[StatusFlags] = None) -> CliResult:
+        """status [--verbose] [--json]"""
+        cmd_args: list[str] = ["status"]
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[StatusFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        if flags.json: result.append("--json")
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_full_feature_client.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_full_feature_client.snap
new file mode 100644
index 00000000..5f6d2ebf
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_full_feature_client.snap
@@ -0,0 +1,83 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: "get_file(&output, \"client.py\")"
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import BuildArgs, BuildFlags, DeployArgs, DeployFlags, EnvChoice, GlobalFlags, MytoolArgs, MytoolFlags, TargetChoice
+
+class Mytool:
+    def __init__(self, bin_path: str = "mytool") -> None:
+        self._runner = CliRunner(bin_path)
+        self.build = Build(self._runner)
+        self.deploy = Deploy(self._runner)
+
+    def exec(self, args: MytoolArgs, flags: Optional[MytoolFlags] = None) -> CliResult:
+        """[FLAGS] <input> <extra>… <SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        if args._input is not None: cmd_args.append(str(args._input))
+        if args.extra is not None: cmd_args.extend(args.extra)
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[MytoolFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose is not None and flags.verbose > 0: result.extend(["--verbose"] * flags.verbose)
+        if flags.config is not None: result.extend(["--config", str(flags.config)])
+        if flags.dry_run: result.append("--dry-run")
+        elif flags.dry_run is False: result.append("--no-dry-run")
+        return result
+
+    @property
+    def b(self) -> Build:
+        """Alias for build."""
+        return self.build
+
+class Build:
+    """Build the project. DEPRECATED: Use compile instead. Aliases: b"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: BuildArgs, flags: Optional[BuildFlags] = None) -> CliResult:
+        """build [-j --jobs… <n>] [--release] <target> <-- output>"""
+        cmd_args: list[str] = ["build"]
+        if args.target is not None: cmd_args.append(str(args.target))
+        cmd_args.append("--")
+        if args.output is not None: cmd_args.append(str(args.output))
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[BuildFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose is not None and flags.verbose > 0: result.extend(["--verbose"] * flags.verbose)
+        if flags.config is not None: result.extend(["--config", str(flags.config)])
+        if flags.jobs is not None:
+            for v in flags.jobs: result.extend(["--jobs", str(v)])
+        if flags.release: result.append("--release")
+        return result
+
+class Deploy:
+    """Deploy the project"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: DeployArgs, flags: Optional[DeployFlags] = None) -> CliResult:
+        """deploy [-f --force] [--confirm] <env> <tags>…"""
+        cmd_args: list[str] = ["deploy"]
+        if args.env is not None: cmd_args.append(str(args.env))
+        if args.tags is not None: cmd_args.extend(args.tags)
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[DeployFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose is not None and flags.verbose > 0: result.extend(["--verbose"] * flags.verbose)
+        if flags.config is not None: result.extend(["--config", str(flags.config)])
+        if flags.force: result.append("--force")
+        if flags.confirm: result.append("--confirm")
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_full_feature_types.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_full_feature_types.snap
new file mode 100644
index 00000000..ff3170fb
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_full_feature_types.snap
@@ -0,0 +1,81 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: "get_file(&output, \"types.py\")"
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+VERSION = "1.2.3"
+ABOUT = "A powerful CLI tool"
+AUTHOR = "Jane Doe"
+
+TargetChoice = Literal["debug", "release"]
+EnvChoice = Literal["staging", "production"]
+
+
+@dataclass
+class GlobalFlags:
+    # Verbosity level. Short: -v
+    verbose: Optional[int] = None
+    # Config file path. Env: MYTOOL_CONFIG. Short: -C
+    config: Optional[str] = None
+
+
+@dataclass
+class MytoolArgs:
+    # Input file
+    _input: str
+    # Extra files
+    extra: list[str]
+
+
+@dataclass
+class MytoolFlags:
+    # Verbosity level. Short: -v
+    verbose: Optional[int] = None
+    # Config file path. Env: MYTOOL_CONFIG. Short: -C
+    config: Optional[str] = None
+    # Show what would be done
+    dry_run: Optional[bool] = None
+
+
+@dataclass
+class BuildArgs:
+    # Build target
+    target: TargetChoice
+    # Output directory
+    output: str
+
+
+@dataclass
+class BuildFlags:
+    # Verbosity level. Short: -v
+    verbose: Optional[int] = None
+    # Config file path. Env: MYTOOL_CONFIG. Short: -C
+    config: Optional[str] = None
+    # Parallel jobs. Short: -j
+    jobs: Optional[list[str]] = None
+    # Build in release mode
+    release: Optional[bool] = None
+
+
+@dataclass
+class DeployArgs:
+    # Target environment
+    env: EnvChoice
+    # Deployment tags
+    tags: list[str]
+
+
+@dataclass
+class DeployFlags:
+    # Verbosity level. Short: -v
+    verbose: Optional[int] = None
+    # Config file path. Env: MYTOOL_CONFIG. Short: -C
+    config: Optional[str] = None
+    # Force deploy. Deprecated: Use --confirm instead. Short: -f
+    force: Optional[bool] = None
+    # Confirm deployment
+    confirm: Optional[bool] = None
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_global_flags_flags_only.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_global_flags_flags_only.snap
new file mode 100644
index 00000000..bd200aab
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_global_flags_flags_only.snap
@@ -0,0 +1,62 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import AppFlags, GlobalFlags, StatusFlags
+
+class App:
+    def __init__(self, bin_path: str = "app") -> None:
+        self._runner = CliRunner(bin_path)
+        self.status = Status(self._runner)
+        self.info = Info(self._runner)
+
+    def exec(self, flags: Optional[AppFlags] = None) -> CliResult:
+        """[-v --verbose] <SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[AppFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        return result
+
+class Status:
+    """Show status"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, flags: Optional[StatusFlags] = None) -> CliResult:
+        """status [--json]"""
+        cmd_args: list[str] = ["status"]
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[StatusFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        if flags.json: result.append("--json")
+        return result
+
+class Info:
+    """Show info"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, flags: Optional[GlobalFlags] = None) -> CliResult:
+        """info"""
+        cmd_args: list[str] = ["info"]
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[GlobalFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.verbose: result.append("--verbose")
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_global_repeatable_flags.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_global_repeatable_flags.snap
new file mode 100644
index 00000000..54cc7034
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_global_repeatable_flags.snap
@@ -0,0 +1,30 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class GlobalFlags:
+    # Repeatable verbose. Short: -v
+    verbose: Optional[list[bool]] = None
+    # Repeatable tag
+    tag: Optional[list[str]] = None
+
+
+@dataclass
+class AppFlags:
+    # Repeatable verbose. Short: -v
+    verbose: Optional[list[bool]] = None
+    # Repeatable tag
+    tag: Optional[list[str]] = None
+
+
+@dataclass
+class RunArgs:
+    target: str
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_hyphenated_subcommands.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_hyphenated_subcommands.snap
new file mode 100644
index 00000000..5246924f
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_hyphenated_subcommands.snap
@@ -0,0 +1,43 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: "get_file(&output, \"client.py\")"
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import AddRemoteArgs, RemoveRemoteArgs
+
+class Cli:
+    def __init__(self, bin_path: str = "cli") -> None:
+        self._runner = CliRunner(bin_path)
+        self.add_remote = AddRemote(self._runner)
+        self.remove_remote = RemoveRemote(self._runner)
+
+    def exec(self) -> CliResult:
+        """<SUBCOMMAND>"""
+        cmd_args: list[str] = []
+        return self._runner.run(cmd_args)
+
+class AddRemote:
+    """Add a remote"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: AddRemoteArgs) -> CliResult:
+        """add-remote <name> <url>"""
+        cmd_args: list[str] = ["add-remote"]
+        if args.name is not None: cmd_args.append(str(args.name))
+        if args.url is not None: cmd_args.append(str(args.url))
+        return self._runner.run(cmd_args)
+
+class RemoveRemote:
+    """Remove a remote"""
+    def __init__(self, runner: CliRunner) -> None:
+        self._runner = runner
+
+    def exec(self, args: RemoveRemoteArgs) -> CliResult:
+        """remove-remote <name>"""
+        cmd_args: list[str] = ["remove-remote"]
+        if args.name is not None: cmd_args.append(str(args.name))
+        return self._runner.run(cmd_args)
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_init.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_init.snap
new file mode 100644
index 00000000..1204907d
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_init.snap
@@ -0,0 +1,7 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: "get_file(&output, \"__init__.py\")"
+---
+from .client import Mycli
+from .runtime import CliResult, CliRunner
+from .types import *
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_minimal.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_minimal.snap
new file mode 100644
index 00000000..8a187cfb
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_minimal.snap
@@ -0,0 +1,16 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: "get_file(&output, \"client.py\")"
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+
+class Hello:
+    def __init__(self, bin_path: str = "hello") -> None:
+        self._runner = CliRunner(bin_path)
+
+    def exec(self) -> CliResult:
+        cmd_args: list[str] = []
+        return self._runner.run(cmd_args)
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_multiple_aliases.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_multiple_aliases.snap
new file mode 100644
index 00000000..d3a9d930
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_multiple_aliases.snap
@@ -0,0 +1,25 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import ToolFlags
+
+class Tool:
+    def __init__(self, bin_path: str = "tool") -> None:
+        self._runner = CliRunner(bin_path)
+
+    def exec(self, flags: Optional[ToolFlags] = None) -> CliResult:
+        """[-f --format <fmt>]"""
+        cmd_args: list[str] = []
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[ToolFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags._format is not None: result.extend(["--format", str(flags._format)])
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_negate_flag_build.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_negate_flag_build.snap
new file mode 100644
index 00000000..edfb9ae2
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_negate_flag_build.snap
@@ -0,0 +1,26 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import AppFlags
+
+class App:
+    def __init__(self, bin_path: str = "app") -> None:
+        self._runner = CliRunner(bin_path)
+
+    def exec(self, flags: Optional[AppFlags] = None) -> CliResult:
+        """[--dry-run]"""
+        cmd_args: list[str] = []
+        flag_args = self._build_flag_args(flags)
+        return self._runner.run(cmd_args + flag_args)
+
+    def _build_flag_args(self, flags: Optional[AppFlags]) -> list[str]:
+        result: list[str] = []
+        if flags is None: return result
+        if flags.dry_run: result.append("--dry-run")
+        elif flags.dry_run is False: result.append("--no-dry-run")
+        return result
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_optional_arg_empty_flags.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_optional_arg_empty_flags.snap
new file mode 100644
index 00000000..b1ae1147
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_optional_arg_empty_flags.snap
@@ -0,0 +1,23 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class AppArgs:
+    # Optional arg without default
+    name: Optional[str] = None
+
+
+@dataclass
+class CheckArgs:
+    # Required arg
+    target: str
+    # Optional arg with default
+    mode: Optional[str] = "quick"
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_optional_variadic_arg.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_optional_variadic_arg.snap
new file mode 100644
index 00000000..3ce110e7
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_optional_variadic_arg.snap
@@ -0,0 +1,19 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: client
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from typing import Optional
+from .runtime import CliResult, CliRunner
+from .types import ToolArgs
+
+class Tool:
+    def __init__(self, bin_path: str = "tool") -> None:
+        self._runner = CliRunner(bin_path)
+
+    def exec(self, args: ToolArgs) -> CliResult:
+        """[files]…"""
+        cmd_args: list[str] = []
+        if args.files is not None: cmd_args.extend(args.files)
+        return self._runner.run(cmd_args)
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_package_name_override.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_package_name_override.snap
new file mode 100644
index 00000000..23f8af6a
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_package_name_override.snap
@@ -0,0 +1,7 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: init
+---
+from .client import MyCustomSdk
+from .runtime import CliResult, CliRunner
+from .types import *
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_required_flag_type.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_required_flag_type.snap
new file mode 100644
index 00000000..326833e1
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_required_flag_type.snap
@@ -0,0 +1,15 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class ToolFlags:
+    # Auth token
+    token: str
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_runtime.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_runtime.snap
new file mode 100644
index 00000000..51deb0ba
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_runtime.snap
@@ -0,0 +1,39 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: "get_file(&output, \"runtime.py\")"
+---
+# Runtime module for usage-generated SDK clients. Do not edit manually.
+from __future__ import annotations
+
+import subprocess
+
+
+class CliResult:
+    """Result of a CLI invocation."""
+
+    def __init__(self, stdout: str, stderr: str, exit_code: int) -> None:
+        self.stdout = stdout
+        self.stderr = stderr
+        self.exit_code = exit_code
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+class CliRunner:
+    """Runs a CLI binary via subprocess."""
+
+    def __init__(self, bin_path: str) -> None:
+        self.bin_path = bin_path
+
+    def run(self, args: list[str]) -> CliResult:
+        try:
+            result = subprocess.run(
+                [self.bin_path, *args],
+                capture_output=True,
+                text=True,
+            )
+            return CliResult(result.stdout, result.stderr, result.returncode)
+        except FileNotFoundError:
+            raise RuntimeError(f"CLI binary not found: {self.bin_path}")
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_types.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_types.snap
new file mode 100644
index 00000000..08ae8a38
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_types.snap
@@ -0,0 +1,52 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: "get_file(&output, \"types.py\")"
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+Arg2Choice = Literal["choice1", "choice2", "choice3"]
+ShellChoice = Literal["bash", "zsh", "fish"]
+
+
+@dataclass
+class MycliArgs:
+    # arg1 description
+    arg1: str
+    # arg3 description
+    arg3: str
+    argrest: list[str]
+    # arg2 description
+    arg2: Optional[Arg2Choice] = "default value"
+    with_default: Optional[str] = "default value"
+
+
+@dataclass
+class MycliFlags:
+    # flag1 description
+    flag1: Optional[bool] = None
+    # flag2 description
+    flag2: Optional[bool] = None
+    # flag3 description
+    flag3: Optional[bool] = None
+    with_default: Optional[bool] = None  # default: default value
+    shell: Optional[ShellChoice] = None
+
+
+@dataclass
+class InstallArgs:
+    plugin: str
+    version: str
+
+
+@dataclass
+class InstallFlags:
+    # Short: -g
+    _global: Optional[bool] = None
+    # Short: -d
+    _dir: Optional[str] = None
+    # Short: -f
+    force: Optional[bool] = None
diff --git a/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_var_value_flag_with_default.snap b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_var_value_flag_with_default.snap
new file mode 100644
index 00000000..5852c07d
--- /dev/null
+++ b/lib/src/sdk/python/snapshots/usage__sdk__python__tests__python_var_value_flag_with_default.snap
@@ -0,0 +1,15 @@
+---
+source: lib/src/sdk/python/mod.rs
+expression: types
+---
+# @generated by usage-cli from test.usage.kdl. Do not edit manually.
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Literal, Optional, Union
+
+
+
+@dataclass
+class ToolFlags:
+    # Tags
+    tag: Optional[list[str]] = None  # default: latest
diff --git a/lib/src/sdk/typescript/mod.rs b/lib/src/sdk/typescript/mod.rs
new file mode 100644
index 00000000..7f9c91c8
--- /dev/null
+++ b/lib/src/sdk/typescript/mod.rs
@@ -0,0 +1,41 @@
+use std::path::PathBuf;
+
+use crate::sdk::{SdkFile, SdkOptions, SdkOutput};
+use crate::Spec;
+
+mod runtime;
+mod types;
+mod wrappers;
+
+pub fn generate(spec: &Spec, opts: &SdkOptions) -> SdkOutput {
+    let package_name = opts
+        .package_name
+        .clone()
+        .unwrap_or_else(|| spec.bin.clone());
+
+    SdkOutput {
+        files: vec![
+            SdkFile {
+                path: PathBuf::from("types.ts"),
+                content: types::render(spec, &package_name, &opts.source_file),
+            },
+            SdkFile {
+                path: PathBuf::from("client.ts"),
+                content: wrappers::render(spec, &package_name, &opts.source_file),
+            },
+            SdkFile {
+                path: PathBuf::from("runtime.ts"),
+                content: runtime::RUNTIME_TS.to_string(),
+            },
+            SdkFile {
+                path: PathBuf::from("index.ts"),
+                content: render_index(&package_name),
+            },
+        ],
+    }
+}
+
+fn render_index(package_name: &str) -> String {
+    let class_name = heck::AsPascalCase(package_name).to_string();
+    format!("export {{ {class_name} }} from \"./client\";\nexport {{ CliResult, CliError }} from \"./runtime\";\nexport * from \"./types\";\n")
+}
diff --git a/lib/src/sdk/typescript/runtime.rs b/lib/src/sdk/typescript/runtime.rs
new file mode 100644
index 00000000..122165eb
--- /dev/null
+++ b/lib/src/sdk/typescript/runtime.rs
@@ -0,0 +1,51 @@
+pub const RUNTIME_TS: &str = r#"// Runtime module for usage-generated SDK clients. Do not edit manually.
+import { spawn, ChildProcess } from "node:child_process";
+
+export class CliResult {
+  constructor(
+    public readonly stdout: string,
+    public readonly stderr: string,
+    public readonly exitCode: number,
+  ) {}
+
+  get ok(): boolean {
+    return this.exitCode === 0;
+  }
+}
+
+export class CliError extends Error {
+  constructor(
+    public readonly binPath: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "CliError";
+  }
+}
+
+export class CliRunner {
+  constructor(private binPath: string) {}
+
+  async run(args: string[]): Promise<CliResult> {
+    return new Promise<CliResult>((resolve, reject) => {
+      const child: ChildProcess = spawn(this.binPath, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout?.setEncoding("utf-8").on("data", (chunk: string) => { stdout += chunk; });
+      child.stderr?.setEncoding("utf-8").on("data", (chunk: string) => { stderr += chunk; });
+      child.on("error", (err: NodeJS.ErrnoException) => {
+        if (err.code === "ENOENT") {
+          reject(new CliError(this.binPath, `CLI binary not found: ${this.binPath}`));
+        } else {
+          reject(err);
+        }
+      });
+      child.on("close", (code: number | null) => {
+        resolve(new CliResult(stdout, stderr, code ?? 1));
+      });
+    });
+  }
+}
+"#;
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__choice_collision.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__choice_collision.snap
new file mode 100644
index 00000000..b3c16ff4
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__choice_collision.snap
@@ -0,0 +1,18 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export type BuildEnvChoice = "debug" | "release";
+export type DeployEnvChoice = "staging" | "production";
+
+export interface BuildArgs {
+  /** Build environment */
+  env: BuildEnvChoice;
+}
+
+export interface DeployArgs {
+  /** Deploy environment */
+  env: DeployEnvChoice;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__deep_nesting.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__deep_nesting.snap
new file mode 100644
index 00000000..eb9f76dd
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__deep_nesting.snap
@@ -0,0 +1,102 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"client.ts\")"
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { CreateArgs, CreateFlags, RunFlags } from "./types";
+
+export class App {
+  private runner: CliRunner;
+  /** Database operations */
+  readonly db: Db;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "app");
+    this.db = new Db(this.runner);
+  }
+  /** <SUBCOMMAND> */
+  async exec(): Promise<CliResult> {
+    return this.runner.run([]);
+  }
+}
+
+/** Database operations */
+export class Db {
+  private runner: CliRunner;
+  /** Migration management */
+  readonly migration: Migration;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+    this.migration = new Migration(this.runner);
+  }
+  /** db <SUBCOMMAND> */
+  async exec(): Promise<CliResult> {
+    return this.runner.run(["db"]);
+  }
+}
+
+/** Migration management */
+export class Migration {
+  private runner: CliRunner;
+  /** Create a new migration */
+  readonly create: Create;
+  /** Run pending migrations */
+  readonly run: Run;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+    this.create = new Create(this.runner);
+    this.run = new Run(this.runner);
+  }
+  /** db migration <SUBCOMMAND> */
+  async exec(): Promise<CliResult> {
+    return this.runner.run(["db", "migration"]);
+  }
+}
+
+/** Create a new migration */
+export class Create {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** db migration create [--template <t>] <name> */
+  async exec(args: CreateArgs, flags?: CreateFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["db", "migration", "create"];
+    if (args.name !== undefined) { cmdArgs.push(String(args.name)); }
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: CreateFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.template !== undefined) { result.push("--template", String(flags.template)); }
+    return result;
+  }
+}
+
+/** Run pending migrations */
+export class Run {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** db migration run [--step <n>] */
+  async exec(flags?: RunFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["db", "migration", "run"];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: RunFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.step !== undefined) { result.push("--step", String(flags.step)); }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__flags_only_subcommand.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__flags_only_subcommand.snap
new file mode 100644
index 00000000..2d17b0df
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__flags_only_subcommand.snap
@@ -0,0 +1,45 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { StatusFlags } from "./types";
+
+export class App {
+  private runner: CliRunner;
+  /** Show status */
+  readonly status: Status;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "app");
+    this.status = new Status(this.runner);
+  }
+  /** <SUBCOMMAND> */
+  async exec(): Promise<CliResult> {
+    return this.runner.run([]);
+  }
+}
+
+/** Show status */
+export class Status {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** status [--verbose] [--json] */
+  async exec(flags?: StatusFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["status"];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: StatusFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose) { result.push("--verbose"); }
+    if (flags.json) { result.push("--json"); }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__full_feature_client.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__full_feature_client.snap
new file mode 100644
index 00000000..bcd553c6
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__full_feature_client.snap
@@ -0,0 +1,106 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"client.ts\")"
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { BuildArgs, BuildFlags, DeployArgs, DeployFlags, EnvChoice, GlobalFlags, MytoolArgs, MytoolFlags, TargetChoice } from "./types";
+
+export class Mytool {
+  private runner: CliRunner;
+  /** Build the project. @deprecated Use 'compile' instead */
+  readonly build: Build;
+  /** Deploy the project */
+  readonly deploy: Deploy;
+  /** Alias for `build` */
+  get b(): Build { return this.build; }
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "mytool");
+    this.build = new Build(this.runner);
+    this.deploy = new Deploy(this.runner);
+  }
+  /** [FLAGS] <input> <extra>… <SUBCOMMAND> */
+  async exec(args: MytoolArgs, flags?: MytoolFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    if (args.input !== undefined) { cmdArgs.push(String(args.input)); }
+    if (args.extra !== undefined) { cmdArgs.push(...args.extra); }
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: MytoolFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose !== undefined && flags.verbose > 0) { for (let i = 0; i < flags.verbose; i++) { result.push("--verbose"); } }
+    if (flags.config !== undefined) { result.push("--config", String(flags.config)); }
+    if (flags.dryRun) { result.push("--dry-run"); }
+    else if (flags.dryRun === false) { result.push("--no-dry-run"); }
+    return result;
+  }
+}
+
+/**
+ * Build the project
+ * @deprecated Use 'compile' instead
+ * Aliases: b
+ */
+export class Build {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /**
+   * build [-j --jobs… <n>] [--release] <target> <-- output>
+   * @example Build in release mode
+   * ```bash
+   * mytool build --release target
+   * ```
+   */
+  async exec(args: BuildArgs, flags?: BuildFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["build"];
+    if (args.target !== undefined) { cmdArgs.push(String(args.target)); }
+    cmdArgs.push("--");
+    if (args.output !== undefined) { cmdArgs.push(String(args.output)); }
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: BuildFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose !== undefined && flags.verbose > 0) { for (let i = 0; i < flags.verbose; i++) { result.push("--verbose"); } }
+    if (flags.config !== undefined) { result.push("--config", String(flags.config)); }
+    if (flags.jobs !== undefined) { for (const v of flags.jobs) { result.push("--jobs", String(v)); } }
+    if (flags.release) { result.push("--release"); }
+    return result;
+  }
+}
+
+/** Deploy the project */
+export class Deploy {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** deploy [-f --force] [--confirm] <env> <tags>… */
+  async exec(args: DeployArgs, flags?: DeployFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["deploy"];
+    if (args.env !== undefined) { cmdArgs.push(String(args.env)); }
+    if (args.tags !== undefined) { cmdArgs.push(...args.tags); }
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: DeployFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose !== undefined && flags.verbose > 0) { for (let i = 0; i < flags.verbose; i++) { result.push("--verbose"); } }
+    if (flags.config !== undefined) { result.push("--config", String(flags.config)); }
+    if (flags.force) { result.push("--force"); }
+    if (flags.confirm) { result.push("--confirm"); }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__full_feature_types.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__full_feature_types.snap
new file mode 100644
index 00000000..a83d44c9
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__full_feature_types.snap
@@ -0,0 +1,60 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"types.ts\")"
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+export const VERSION = "1.2.3";
+/** A powerful CLI tool */
+export const ABOUT = "A powerful CLI tool";
+export const AUTHOR = "Jane Doe";
+
+export type TargetChoice = "debug" | "release";
+export type EnvChoice = "staging" | "production";
+
+/** Global flags available on all subcommands. */
+export interface GlobalFlags {
+  /** Verbosity level */
+  verbose?: number;
+  /** Config file path. Environment variable: MYTOOL_CONFIG */
+  config?: string;
+}
+
+export interface MytoolArgs {
+  /** Input file */
+  input: string;
+  /** Extra files */
+  extra: string[];
+}
+
+export interface MytoolFlags extends GlobalFlags {
+  /** Show what would be done */
+  dryRun?: boolean;
+}
+
+export interface BuildArgs {
+  /** Build target */
+  target: TargetChoice;
+  /** Output directory */
+  output: string;
+}
+
+export interface BuildFlags extends GlobalFlags {
+  /** Parallel jobs */
+  jobs?: string[];
+  /** Build in release mode */
+  release?: boolean;
+}
+
+export interface DeployArgs {
+  /** Target environment */
+  env: EnvChoice;
+  /** Deployment tags. Min count: 1. Max count: 5 */
+  tags: string[];
+}
+
+export interface DeployFlags extends GlobalFlags {
+  /** Force deploy. @deprecated Use --confirm instead */
+  force?: boolean;
+  /** Confirm deployment */
+  confirm?: boolean;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__hyphenated_subcommands.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__hyphenated_subcommands.snap
new file mode 100644
index 00000000..e2cef293
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__hyphenated_subcommands.snap
@@ -0,0 +1,56 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"client.ts\")"
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { AddRemoteArgs, RemoveRemoteArgs } from "./types";
+
+export class Cli {
+  private runner: CliRunner;
+  /** Add a remote */
+  readonly addRemote: AddRemote;
+  /** Remove a remote */
+  readonly removeRemote: RemoveRemote;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "cli");
+    this.addRemote = new AddRemote(this.runner);
+    this.removeRemote = new RemoveRemote(this.runner);
+  }
+  /** <SUBCOMMAND> */
+  async exec(): Promise<CliResult> {
+    return this.runner.run([]);
+  }
+}
+
+/** Add a remote */
+export class AddRemote {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** add-remote <name> <url> */
+  async exec(args: AddRemoteArgs): Promise<CliResult> {
+    const cmdArgs: string[] = ["add-remote"];
+    if (args.name !== undefined) { cmdArgs.push(String(args.name)); }
+    if (args.url !== undefined) { cmdArgs.push(String(args.url)); }
+    return this.runner.run(cmdArgs);
+  }
+}
+
+/** Remove a remote */
+export class RemoveRemote {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** remove-remote <name> */
+  async exec(args: RemoveRemoteArgs): Promise<CliResult> {
+    const cmdArgs: string[] = ["remove-remote"];
+    if (args.name !== undefined) { cmdArgs.push(String(args.name)); }
+    return this.runner.run(cmdArgs);
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__minimal_spec.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__minimal_spec.snap
new file mode 100644
index 00000000..ab68552d
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__minimal_spec.snap
@@ -0,0 +1,17 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"client.ts\")"
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+
+export class Hello {
+  private runner: CliRunner;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "hello");
+  }
+  async exec(): Promise<CliResult> {
+    return this.runner.run([]);
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__package_name_override.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__package_name_override.snap
new file mode 100644
index 00000000..1a7c533e
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__package_name_override.snap
@@ -0,0 +1,7 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"index.ts\")"
+---
+export { MyCustomSdk } from "./client";
+export { CliResult, CliError } from "./runtime";
+export * from "./types";
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_arg_defaults.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_arg_defaults.snap
new file mode 100644
index 00000000..b884c170
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_arg_defaults.snap
@@ -0,0 +1,12 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface RunnerArgs {
+  /** Run mode */
+  mode?: string;
+  /** Output path */
+  output: string;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_boolean_flag_default_false.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_boolean_flag_default_false.snap
new file mode 100644
index 00000000..dabbe87f
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_boolean_flag_default_false.snap
@@ -0,0 +1,10 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface AppFlags {
+  /** Disable cache. @default false */
+  noCache?: boolean;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_client.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_client.snap
new file mode 100644
index 00000000..19feb609
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_client.snap
@@ -0,0 +1,81 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"client.ts\")"
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { Arg2Choice, InstallArgs, InstallFlags, MycliArgs, MycliFlags, ShellChoice } from "./types";
+
+export class Mycli {
+  private runner: CliRunner;
+  readonly plugin: Plugin;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "mycli");
+    this.plugin = new Plugin(this.runner);
+  }
+  /** [FLAGS] <ARGS>… <SUBCOMMAND> */
+  async exec(args: MycliArgs, flags?: MycliFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    if (args.arg1 !== undefined) { cmdArgs.push(String(args.arg1)); }
+    if (args.arg2 !== undefined) { cmdArgs.push(String(args.arg2)); }
+    if (args.arg3 !== undefined) { cmdArgs.push(String(args.arg3)); }
+    if (args.argrest !== undefined) { cmdArgs.push(...args.argrest); }
+    if (args.withDefault !== undefined) { cmdArgs.push(String(args.withDefault)); }
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: MycliFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.flag1) { result.push("--flag1"); }
+    if (flags.flag2) { result.push("--flag2"); }
+    if (flags.flag3) { result.push("--flag3"); }
+    else if (flags.flag3 === false) { result.push("--no-flag3"); }
+    if (flags.withDefault) { result.push("--with-default"); }
+    if (flags.shell !== undefined) { result.push("--shell", String(flags.shell)); }
+    return result;
+  }
+}
+
+export class Plugin {
+  private runner: CliRunner;
+  readonly install: Install;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+    this.install = new Install(this.runner);
+  }
+  /** plugin <SUBCOMMAND> */
+  async exec(): Promise<CliResult> {
+    return this.runner.run(["plugin"]);
+  }
+}
+
+/** install a plugin */
+export class Install {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** plugin install [FLAGS] <plugin> <version> */
+  async exec(args: InstallArgs, flags?: InstallFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["plugin", "install"];
+    if (args.plugin !== undefined) { cmdArgs.push(String(args.plugin)); }
+    if (args.version !== undefined) { cmdArgs.push(String(args.version)); }
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: InstallFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.global) { result.push("--global"); }
+    if (flags.dir !== undefined) { result.push("--dir", String(flags.dir)); }
+    if (flags.force) { result.push("--force"); }
+    else if (flags.force === false) { result.push("--no-force"); }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_client_edge_cases.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_client_edge_cases.snap
new file mode 100644
index 00000000..2b4f2460
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_client_edge_cases.snap
@@ -0,0 +1,90 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { GlobalFlags, RunArgs, RunnerArgs, RunnerFlags } from "./types";
+
+export class Runner {
+  private runner: CliRunner;
+  /** Run a task */
+  readonly run: Run;
+  /** Show info */
+  readonly info: Info;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "runner");
+    this.run = new Run(this.runner);
+    this.info = new Info(this.runner);
+  }
+  /** [-v --verbose] [--debug…] <input> <extra>… <SUBCOMMAND> */
+  async exec(args: RunnerArgs, flags?: RunnerFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    if (args.input !== undefined) { cmdArgs.push(String(args.input)); }
+    if (args.extra !== undefined) { cmdArgs.push(...args.extra); }
+    // double_dash=automatic: "--" is implied after the first positional arg
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: RunnerFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose) { result.push("--verbose"); }
+    if (flags.debug !== undefined) { for (const v of flags.debug) { if (v) result.push("--debug"); } }
+    return result;
+  }
+}
+
+/** Run a task */
+export class Run {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /**
+   * run <task>
+   * @example Basic run
+   * ```bash
+   * runner run hello
+   * ```
+   */
+  async exec(args: RunArgs, flags?: GlobalFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["run"];
+    if (args.task !== undefined) { cmdArgs.push(String(args.task)); }
+    // double_dash=automatic: "--" is implied after the first positional arg
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: GlobalFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose) { result.push("--verbose"); }
+    return result;
+  }
+}
+
+/** Show info */
+export class Info {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** info */
+  async exec(flags?: GlobalFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["info"];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: GlobalFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose) { result.push("--verbose"); }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_all_optional.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_all_optional.snap
new file mode 100644
index 00000000..e85a3214
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_all_optional.snap
@@ -0,0 +1,10 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface AppConfig {
+  debug?: boolean;
+  port?: number;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_and_flag_edge_cases.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_and_flag_edge_cases.snap
new file mode 100644
index 00000000..631ebf49
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_and_flag_edge_cases.snap
@@ -0,0 +1,28 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface MyappArgs {
+  /** Input file. Environment variable: MYAPP_INPUT */
+  input: string;
+}
+
+export interface MyappFlags {
+  /** Reserved keyword. @deprecated Use --kind */
+  _type?: boolean;
+  /** Flag with short and long alias. Aliases: --fmt */
+  format?: string;
+  /** Short-only flag */
+  v?: boolean;
+}
+
+export interface MyappConfig {
+  /** Enable debug mode */
+  debug?: boolean;
+  extra: unknown;
+  host: string;
+  port?: number;
+  rate?: number;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_boolean_default_false.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_boolean_default_false.snap
new file mode 100644
index 00000000..6862a369
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_boolean_default_false.snap
@@ -0,0 +1,12 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface AppConfig {
+  /** Dry run mode */
+  dry_run?: boolean;
+  /** Verbose output */
+  verbose?: boolean;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_string_with_default.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_string_with_default.snap
new file mode 100644
index 00000000..bd8b6938
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_config_string_with_default.snap
@@ -0,0 +1,11 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface AppConfig {
+  /** Server host */
+  host?: string;
+  name?: string;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_count_flag_build.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_count_flag_build.snap
new file mode 100644
index 00000000..635fdc4b
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_count_flag_build.snap
@@ -0,0 +1,28 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { AppFlags } from "./types";
+
+export class App {
+  private runner: CliRunner;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "app");
+  }
+  /** [-v --verbose] */
+  async exec(flags?: AppFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: AppFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose !== undefined && flags.verbose > 0) { for (let i = 0; i < flags.verbose; i++) { result.push("--verbose"); } }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_double_dash_automatic.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_double_dash_automatic.snap
new file mode 100644
index 00000000..44804b97
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_double_dash_automatic.snap
@@ -0,0 +1,56 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { RunArgs, RunnerArgs, RunnerFlags } from "./types";
+
+export class Runner {
+  private runner: CliRunner;
+  /** Run a task */
+  readonly run: Run;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "runner");
+    this.run = new Run(this.runner);
+  }
+  /** [--verbose…] <input> <extra>… <SUBCOMMAND> */
+  async exec(args: RunnerArgs, flags?: RunnerFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    if (args.input !== undefined) { cmdArgs.push(String(args.input)); }
+    if (args.extra !== undefined) { cmdArgs.push(...args.extra); }
+    // double_dash=automatic: "--" is implied after the first positional arg
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: RunnerFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose !== undefined) { for (const v of flags.verbose) { if (v) result.push("--verbose"); } }
+    return result;
+  }
+}
+
+/** Run a task */
+export class Run {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /**
+   * run <task>
+   * @example Basic run
+   * ```
+   * runner run hello
+   * ```
+   */
+  async exec(args: RunArgs): Promise<CliResult> {
+    const cmdArgs: string[] = ["run"];
+    if (args.task !== undefined) { cmdArgs.push(String(args.task)); }
+    // double_dash=automatic: "--" is implied after the first positional arg
+    return this.runner.run(cmdArgs);
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_example_without_lang.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_example_without_lang.snap
new file mode 100644
index 00000000..52d95933
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_example_without_lang.snap
@@ -0,0 +1,43 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { GreetArgs } from "./types";
+
+export class App {
+  private runner: CliRunner;
+  /** Greet someone */
+  readonly greet: Greet;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "app");
+    this.greet = new Greet(this.runner);
+  }
+  /** <SUBCOMMAND> */
+  async exec(): Promise<CliResult> {
+    return this.runner.run([]);
+  }
+}
+
+/** Greet someone */
+export class Greet {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /**
+   * greet <name>
+   * @example Example
+   * ```
+   * app greet hello
+   * ```
+   */
+  async exec(args: GreetArgs): Promise<CliResult> {
+    const cmdArgs: string[] = ["greet"];
+    if (args.name !== undefined) { cmdArgs.push(String(args.name)); }
+    return this.runner.run(cmdArgs);
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_edge_cases-2.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_edge_cases-2.snap
new file mode 100644
index 00000000..5dfcd5fd
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_edge_cases-2.snap
@@ -0,0 +1,33 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { ToolFlags } from "./types";
+
+export class Tool {
+  private runner: CliRunner;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "tool");
+  }
+  /** <FLAGS> */
+  async exec(flags?: ToolFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: ToolFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.v) { result.push("-v"); }
+    if (flags._type) { result.push("--type"); }
+    if (flags.level !== undefined && flags.level > 0) { for (let i = 0; i < flags.level; i++) { result.push("--level"); } }
+    if (flags.format !== undefined) { result.push("--format", String(flags.format)); }
+    if (flags.confirm) { result.push("--confirm"); }
+    if (flags.verbose !== undefined) { for (const v of flags.verbose) { if (v) result.push("--verbose"); } }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_edge_cases.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_edge_cases.snap
new file mode 100644
index 00000000..ad5a8da2
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_edge_cases.snap
@@ -0,0 +1,20 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface ToolFlags {
+  /** Short-only flag */
+  v?: boolean;
+  /** Reserved keyword. @deprecated Use --kind */
+  _type?: boolean;
+  /** Count flag with default. @default 2 */
+  level?: number;
+  /** Value flag with default. @default json */
+  format?: string;
+  /** Required flag */
+  confirm: boolean;
+  /** Repeatable boolean flag */
+  verbose?: boolean[];
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_with_choices.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_with_choices.snap
new file mode 100644
index 00000000..25e5eeda
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_with_choices.snap
@@ -0,0 +1,12 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export type ShellChoice = "bash" | "zsh" | "fish";
+
+export interface ToolFlags {
+  /** Shell type */
+  shell?: ShellChoice;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_with_env.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_with_env.snap
new file mode 100644
index 00000000..78442c4b
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_flag_with_env.snap
@@ -0,0 +1,10 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface AppFlags {
+  /** Config file. Environment variable: APP_CONFIG */
+  config?: string;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_global_flags_flags_only.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_global_flags_flags_only.snap
new file mode 100644
index 00000000..ebedb9c6
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_global_flags_flags_only.snap
@@ -0,0 +1,79 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { AppFlags, GlobalFlags, StatusFlags } from "./types";
+
+export class App {
+  private runner: CliRunner;
+  /** Show status */
+  readonly status: Status;
+  /** Show info */
+  readonly info: Info;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "app");
+    this.status = new Status(this.runner);
+    this.info = new Info(this.runner);
+  }
+  /** [-v --verbose] <SUBCOMMAND> */
+  async exec(flags?: AppFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: AppFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose) { result.push("--verbose"); }
+    return result;
+  }
+}
+
+/** Show status */
+export class Status {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** status [--json] */
+  async exec(flags?: StatusFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["status"];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: StatusFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose) { result.push("--verbose"); }
+    if (flags.json) { result.push("--json"); }
+    return result;
+  }
+}
+
+/** Show info */
+export class Info {
+  private runner: CliRunner;
+
+  constructor(runner: CliRunner) {
+    this.runner = runner;
+  }
+  /** info */
+  async exec(flags?: GlobalFlags): Promise<CliResult> {
+    const cmdArgs: string[] = ["info"];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: GlobalFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.verbose) { result.push("--verbose"); }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_global_repeatable_flags.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_global_repeatable_flags.snap
new file mode 100644
index 00000000..7765b26c
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_global_repeatable_flags.snap
@@ -0,0 +1,20 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+/** Global flags available on all subcommands. */
+export interface GlobalFlags {
+  /** Repeatable verbose */
+  verbose?: boolean[];
+  /** Repeatable tag */
+  tag?: string[];
+}
+
+export interface AppFlags extends GlobalFlags {
+}
+
+export interface RunArgs {
+  target: string;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_index.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_index.snap
new file mode 100644
index 00000000..6f24da8a
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_index.snap
@@ -0,0 +1,7 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"index.ts\")"
+---
+export { Mycli } from "./client";
+export { CliResult, CliError } from "./runtime";
+export * from "./types";
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_multiple_aliases.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_multiple_aliases.snap
new file mode 100644
index 00000000..45c6cf9b
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_multiple_aliases.snap
@@ -0,0 +1,28 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { ToolFlags } from "./types";
+
+export class Tool {
+  private runner: CliRunner;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "tool");
+  }
+  /** [-f --format <fmt>] */
+  async exec(flags?: ToolFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: ToolFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.format !== undefined) { result.push("--format", String(flags.format)); }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_negate_flag_build.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_negate_flag_build.snap
new file mode 100644
index 00000000..158d922a
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_negate_flag_build.snap
@@ -0,0 +1,29 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { AppFlags } from "./types";
+
+export class App {
+  private runner: CliRunner;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "app");
+  }
+  /** [--dry-run] */
+  async exec(flags?: AppFlags): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    const flagArgs = this.buildFlagArgs(flags);
+    return this.runner.run([...cmdArgs, ...flagArgs]);
+  }
+
+  private buildFlagArgs(flags?: AppFlags): string[] {
+    const result: string[] = [];
+    if (!flags) return result;
+    if (flags.dryRun) { result.push("--dry-run"); }
+    else if (flags.dryRun === false) { result.push("--no-dry-run"); }
+    return result;
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_optional_arg_empty_flags.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_optional_arg_empty_flags.snap
new file mode 100644
index 00000000..f2440ad0
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_optional_arg_empty_flags.snap
@@ -0,0 +1,17 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface AppArgs {
+  /** Optional arg without default */
+  name?: string;
+}
+
+export interface CheckArgs {
+  /** Required arg */
+  target: string;
+  /** Optional arg with default */
+  mode?: string;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_optional_variadic_arg.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_optional_variadic_arg.snap
new file mode 100644
index 00000000..28f976a6
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_optional_variadic_arg.snap
@@ -0,0 +1,21 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: client
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+import { CliRunner, CliResult } from "./runtime";
+import { ToolArgs } from "./types";
+
+export class Tool {
+  private runner: CliRunner;
+
+  constructor(binPath?: string) {
+    this.runner = new CliRunner(binPath ?? "tool");
+  }
+  /** [files]… */
+  async exec(args: ToolArgs): Promise<CliResult> {
+    const cmdArgs: string[] = [];
+    if (args.files !== undefined) { cmdArgs.push(...args.files); }
+    return this.runner.run(cmdArgs);
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_required_flag_type.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_required_flag_type.snap
new file mode 100644
index 00000000..9f35ba84
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_required_flag_type.snap
@@ -0,0 +1,10 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface ToolFlags {
+  /** Auth token */
+  token: string;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_runtime.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_runtime.snap
new file mode 100644
index 00000000..d23bc29f
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_runtime.snap
@@ -0,0 +1,54 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"runtime.ts\")"
+---
+// Runtime module for usage-generated SDK clients. Do not edit manually.
+import { spawn, ChildProcess } from "node:child_process";
+
+export class CliResult {
+  constructor(
+    public readonly stdout: string,
+    public readonly stderr: string,
+    public readonly exitCode: number,
+  ) {}
+
+  get ok(): boolean {
+    return this.exitCode === 0;
+  }
+}
+
+export class CliError extends Error {
+  constructor(
+    public readonly binPath: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "CliError";
+  }
+}
+
+export class CliRunner {
+  constructor(private binPath: string) {}
+
+  async run(args: string[]): Promise<CliResult> {
+    return new Promise<CliResult>((resolve, reject) => {
+      const child: ChildProcess = spawn(this.binPath, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout?.setEncoding("utf-8").on("data", (chunk: string) => { stdout += chunk; });
+      child.stderr?.setEncoding("utf-8").on("data", (chunk: string) => { stderr += chunk; });
+      child.on("error", (err: NodeJS.ErrnoException) => {
+        if (err.code === "ENOENT") {
+          reject(new CliError(this.binPath, `CLI binary not found: ${this.binPath}`));
+        } else {
+          reject(err);
+        }
+      });
+      child.on("close", (code: number | null) => {
+        resolve(new CliResult(stdout, stderr, code ?? 1));
+      });
+    });
+  }
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_types.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_types.snap
new file mode 100644
index 00000000..09837b35
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_types.snap
@@ -0,0 +1,42 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: "get_file(&output, \"types.ts\")"
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export type Arg2Choice = "choice1" | "choice2" | "choice3";
+export type ShellChoice = "bash" | "zsh" | "fish";
+
+export interface MycliArgs {
+  /** arg1 description */
+  arg1: string;
+  /** arg2 description */
+  arg2?: Arg2Choice;
+  /** arg3 description */
+  arg3: string;
+  argrest: string[];
+  withDefault?: string;
+}
+
+export interface MycliFlags {
+  /** flag1 description */
+  flag1?: boolean;
+  /** flag2 description */
+  flag2?: boolean;
+  /** flag3 description */
+  flag3?: boolean;
+  /** @default default value */
+  withDefault?: boolean;
+  shell?: ShellChoice;
+}
+
+export interface InstallArgs {
+  plugin: string;
+  version: string;
+}
+
+export interface InstallFlags {
+  global?: boolean;
+  dir?: string;
+  force?: boolean;
+}
diff --git a/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_var_value_flag_with_default.snap b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_var_value_flag_with_default.snap
new file mode 100644
index 00000000..33e618e8
--- /dev/null
+++ b/lib/src/sdk/typescript/snapshots/usage__sdk__typescript__types__tests__typescript_var_value_flag_with_default.snap
@@ -0,0 +1,10 @@
+---
+source: lib/src/sdk/typescript/types.rs
+expression: types
+---
+// @generated by usage-cli from test.usage.kdl. Do not edit manually.
+
+export interface ToolFlags {
+  /** Tags. @default latest */
+  tag?: string[];
+}
diff --git a/lib/src/sdk/typescript/types.rs b/lib/src/sdk/typescript/types.rs
new file mode 100644
index 00000000..66f7d64c
--- /dev/null
+++ b/lib/src/sdk/typescript/types.rs
@@ -0,0 +1,1041 @@
+use heck::AsPascalCase;
+
+use crate::spec::cmd::SpecCommand;
+use crate::spec::config::SpecConfigProp;
+use crate::spec::data_types::SpecDataTypes;
+use crate::{Spec, SpecArg, SpecFlag};
+
+use crate::sdk::{
+    collect_choice_types, command_type_name, escape_jsdoc, escape_ts_string, generated_header,
+    ChoiceTypeMap, CodeWriter,
+};
+
+pub fn render(spec: &Spec, package_name: &str, source_file: &Option<String>) -> String {
+    let mut w = CodeWriter::new();
+
+    w.line(&generated_header("//", source_file));
+
+    // spec metadata constants
+    if let Some(version) = &spec.version {
+        w.line(&format!(
+            "export const VERSION = \"{}\";",
+            escape_ts_string(version)
+        ));
+    }
+    if let Some(about) = &spec.about {
+        w.line(&format!("/** {} */", escape_jsdoc(about)));
+        w.line(&format!(
+            "export const ABOUT = \"{}\";",
+            escape_ts_string(about)
+        ));
+    }
+    if let Some(author) = &spec.author {
+        w.line(&format!(
+            "export const AUTHOR = \"{}\";",
+            escape_ts_string(author)
+        ));
+    }
+
+    let choice_types = collect_choice_types(&spec.cmd);
+
+    // collect root-level global flags
+    let root_global_flags: Vec<&SpecFlag> = spec
+        .cmd
+        .flags
+        .iter()
+        .filter(|f| f.global && !f.hide)
+        .collect();
+    let has_global_flags = !root_global_flags.is_empty();
+
+    if !choice_types.is_empty() {
+        w.line("");
+        for (name, choices) in choice_types.iter() {
+            let union = choices
+                .iter()
+                .map(|c| format!("\"{}\"", escape_ts_string(c)))
+                .collect::<Vec<_>>()
+                .join(" | ");
+            w.line(&format!("export type {name} = {union};"));
+        }
+    }
+
+    // render GlobalFlags interface if root has global flags
+    if has_global_flags {
+        w.line("");
+        w.line("/** Global flags available on all subcommands. */");
+        w.line("export interface GlobalFlags {");
+        w.indent();
+        for flag in &root_global_flags {
+            let prop = flag_property_name(flag);
+            let ts_type = flag_ts_simple(flag);
+            let optional = if flag.required { "" } else { "?" };
+            let mut doc_parts = Vec::new();
+            if let Some(help) = &flag.help {
+                doc_parts.push(help.clone());
+            }
+            if let Some(env) = &flag.env {
+                doc_parts.push(format!("Environment variable: {env}"));
+            }
+            if !doc_parts.is_empty() {
+                w.line(&format!("/** {} */", escape_jsdoc(&doc_parts.join(". "))));
+            }
+            w.line(&format!("{prop}{optional}: {ts_type};"));
+        }
+        w.dedent();
+        w.line("}");
+    }
+
+    render_command_types(
+        &spec.cmd,
+        package_name,
+        &choice_types,
+        has_global_flags,
+        &mut w,
+    );
+
+    if !spec.config.props.is_empty() {
+        w.line("");
+        let config_name = format!("{}Config", AsPascalCase(package_name));
+        w.line(&format!("export interface {config_name} {{"));
+        w.indent();
+        for (name, prop) in &spec.config.props {
+            let ts_type = config_prop_type(prop);
+            let optional = if prop.default.is_some() { "?" } else { "" };
+            if let Some(help) = &prop.help {
+                w.line(&format!("/** {} */", escape_jsdoc(help)));
+            }
+            w.line(&format!("{name}{optional}: {ts_type};"));
+        }
+        w.dedent();
+        w.line("}");
+    }
+
+    w.finish()
+}
+
+fn render_command_types(
+    cmd: &SpecCommand,
+    package_name: &str,
+    choice_types: &ChoiceTypeMap,
+    has_global_flags: bool,
+    w: &mut CodeWriter,
+) {
+    if cmd.hide {
+        return;
+    }
+
+    let name = command_type_name(cmd, package_name);
+    let cmd_name = &cmd.name;
+
+    let visible_args: Vec<&SpecArg> = cmd.args.iter().filter(|a| !a.hide).collect();
+    let visible_flags: Vec<&SpecFlag> = cmd.flags.iter().filter(|f| !f.hide).collect();
+
+    if !visible_args.is_empty() {
+        w.line("");
+        w.line(&format!("export interface {name}Args {{"));
+        w.indent();
+        for arg in &visible_args {
+            render_arg_field(arg, cmd_name, choice_types, w);
+        }
+        w.dedent();
+        w.line("}");
+    }
+
+    if !visible_flags.is_empty() {
+        w.line("");
+        if has_global_flags {
+            w.line(&format!(
+                "export interface {name}Flags extends GlobalFlags {{"
+            ));
+        } else {
+            w.line(&format!("export interface {name}Flags {{"));
+        }
+        w.indent();
+        for flag in &visible_flags {
+            if has_global_flags && flag.global {
+                continue;
+            }
+            render_flag_field(flag, cmd_name, choice_types, w);
+        }
+        w.dedent();
+        w.line("}");
+    }
+
+    for subcmd in cmd.subcommands.values() {
+        render_command_types(subcmd, package_name, choice_types, has_global_flags, w);
+    }
+}
+
+fn render_arg_field(
+    arg: &SpecArg,
+    cmd_name: &str,
+    choice_types: &ChoiceTypeMap,
+    w: &mut CodeWriter,
+) {
+    let ts_type = arg_ts_type(arg, cmd_name, choice_types);
+    let optional = if arg.required && arg.default.is_empty() {
+        ""
+    } else {
+        "?"
+    };
+    let mut doc_parts = Vec::new();
+    if let Some(help) = &arg.help {
+        doc_parts.push(help.clone());
+    }
+    if let Some(env) = &arg.env {
+        doc_parts.push(format!("Environment variable: {env}"));
+    }
+    if arg.var {
+        if let Some(min) = arg.var_min {
+            doc_parts.push(format!("Min count: {min}"));
+        }
+        if let Some(max) = arg.var_max {
+            doc_parts.push(format!("Max count: {max}"));
+        }
+    }
+    if !doc_parts.is_empty() {
+        w.line(&format!("/** {} */", escape_jsdoc(&doc_parts.join(". "))));
+    }
+    w.line(&format!(
+        "{}{optional}: {ts_type};",
+        sanitize_ident(&arg.name)
+    ));
+}
+
+fn render_flag_field(
+    flag: &SpecFlag,
+    cmd_name: &str,
+    choice_types: &ChoiceTypeMap,
+    w: &mut CodeWriter,
+) {
+    let ts_type = flag_ts_type(flag, cmd_name, choice_types);
+    let optional = if flag.required && flag.default.is_empty() {
+        ""
+    } else {
+        "?"
+    };
+    let mut doc_parts = Vec::new();
+    if let Some(help) = &flag.help {
+        doc_parts.push(help.clone());
+    }
+    if let Some(env) = &flag.env {
+        doc_parts.push(format!("Environment variable: {env}"));
+    }
+    if let Some(deprecated) = &flag.deprecated {
+        doc_parts.push(format!("@deprecated {deprecated}"));
+    }
+    if !flag.default.is_empty() {
+        doc_parts.push(format!("@default {}", flag.default.join(", ")));
+    }
+    // document flag aliases
+    let alias_strs: Vec<String> = flag
+        .short
+        .iter()
+        .skip(1)
+        .map(|c| format!("-{c}"))
+        .chain(flag.long.iter().skip(1).map(|l| format!("--{l}")))
+        .collect();
+    if !alias_strs.is_empty() {
+        doc_parts.push(format!("Aliases: {}", alias_strs.join(", ")));
+    }
+    if !doc_parts.is_empty() {
+        w.line(&format!("/** {} */", escape_jsdoc(&doc_parts.join(". "))));
+    }
+    let prop_name = flag_property_name(flag);
+    w.line(&format!("{prop_name}{optional}: {ts_type};"));
+}
+
+fn arg_ts_type(arg: &SpecArg, cmd_name: &str, choice_types: &ChoiceTypeMap) -> String {
+    let base = if let Some(choices) = &arg.choices {
+        if let Some(resolved) = choice_types.lookup(cmd_name, &arg.name) {
+            resolved.to_string()
+        } else {
+            choices
+                .choices
+                .iter()
+                .map(|c| format!("\"{}\"", escape_ts_string(c)))
+                .collect::<Vec<_>>()
+                .join(" | ")
+        }
+    } else {
+        "string".to_string()
+    };
+
+    if arg.var {
+        format!("{base}[]")
+    } else {
+        base
+    }
+}
+
+fn flag_ts_type(flag: &SpecFlag, cmd_name: &str, choice_types: &ChoiceTypeMap) -> String {
+    if flag.count {
+        return "number".to_string();
+    }
+
+    match &flag.arg {
+        Some(arg) => {
+            let base = if let Some(choices) = &arg.choices {
+                if let Some(resolved) = choice_types.lookup(cmd_name, &flag.name) {
+                    resolved.to_string()
+                } else {
+                    choices
+                        .choices
+                        .iter()
+                        .map(|c| format!("\"{}\"", escape_ts_string(c)))
+                        .collect::<Vec<_>>()
+                        .join(" | ")
+                }
+            } else {
+                "string".to_string()
+            };
+
+            if flag.var {
+                format!("{base}[]")
+            } else {
+                base
+            }
+        }
+        None => {
+            if flag.var {
+                "boolean[]".to_string()
+            } else {
+                "boolean".to_string()
+            }
+        }
+    }
+}
+
+fn flag_ts_simple(flag: &SpecFlag) -> String {
+    if flag.count {
+        return "number".to_string();
+    }
+    match &flag.arg {
+        Some(_) => {
+            if flag.var {
+                "string[]".to_string()
+            } else {
+                "string".to_string()
+            }
+        }
+        None => {
+            if flag.var {
+                "boolean[]".to_string()
+            } else {
+                "boolean".to_string()
+            }
+        }
+    }
+}
+
+fn config_prop_type(prop: &SpecConfigProp) -> String {
+    match prop.data_type {
+        SpecDataTypes::String => "string".to_string(),
+        SpecDataTypes::Integer => "number".to_string(),
+        SpecDataTypes::Float => "number".to_string(),
+        SpecDataTypes::Boolean => "boolean".to_string(),
+        SpecDataTypes::Null => "unknown".to_string(),
+    }
+}
+
+pub(crate) fn flag_property_name(flag: &SpecFlag) -> String {
+    if let Some(long) = flag.long.first() {
+        return sanitize_ident(&heck::AsLowerCamelCase(long).to_string());
+    }
+    if let Some(short) = flag.short.first() {
+        return short.to_string();
+    }
+    sanitize_ident(&flag.name)
+}
+
+pub(crate) fn sanitize_ident(name: &str) -> String {
+    let camel = heck::AsLowerCamelCase(name).to_string();
+    match camel.as_str() {
+        "function" | "class" | "const" | "let" | "var" | "type" | "interface" | "new"
+        | "delete" | "return" | "export" | "import" | "default" | "in" | "instanceof" => {
+            format!("_{camel}")
+        }
+        _ => camel,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::sdk::{SdkLanguage, SdkOptions};
+    use crate::test::SPEC_KITCHEN_SINK;
+    use crate::Spec;
+
+    fn make_opts() -> SdkOptions {
+        SdkOptions {
+            language: SdkLanguage::TypeScript,
+            package_name: None,
+            source_file: Some("test.usage.kdl".to_string()),
+        }
+    }
+
+    fn get_file<'a>(output: &'a crate::sdk::SdkOutput, name: &str) -> &'a str {
+        output
+            .files
+            .iter()
+            .find(|f| f.path.to_str() == Some(name))
+            .unwrap_or_else(|| panic!("{name} should exist"))
+            .content
+            .as_str()
+    }
+
+    #[test]
+    fn test_typescript_types() {
+        let output = super::super::super::generate(&SPEC_KITCHEN_SINK, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "types.ts"));
+    }
+
+    #[test]
+    fn test_typescript_client() {
+        let output = super::super::super::generate(&SPEC_KITCHEN_SINK, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.ts"));
+    }
+
+    #[test]
+    fn test_typescript_runtime() {
+        let output = super::super::super::generate(&SPEC_KITCHEN_SINK, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "runtime.ts"));
+    }
+
+    #[test]
+    fn test_typescript_index() {
+        let output = super::super::super::generate(&SPEC_KITCHEN_SINK, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "index.ts"));
+    }
+
+    /// Spec with version, about, author, global flags, double_dash,
+    /// deprecated, aliases, examples, repeatable value flags.
+    fn full_feature_spec() -> Spec {
+        let spec: Spec = r##"
+            bin "mytool"
+            name "mytool"
+            version "1.2.3"
+            about "A powerful CLI tool"
+            author "Jane Doe"
+
+            flag "-v --verbose" help="Verbosity level" count=#true global=#true
+            flag "-C --config <path>" help="Config file path" global=#true env="MYTOOL_CONFIG"
+            flag "--dry-run" help="Show what would be done" negate="--no-dry-run"
+
+            arg "input" help="Input file" required=#true
+            arg "extra" var=#true help="Extra files"
+
+            cmd "build" help="Build the project" deprecated="Use 'compile' instead" {
+                alias "b"
+                arg "target" help="Build target" {
+                    choices "debug" "release"
+                }
+                arg "output" help="Output directory" double_dash="required"
+                flag "-j --jobs <n>" help="Parallel jobs" var=#true
+                flag "--release" help="Build in release mode"
+                example "mytool build --release target" header="Build in release mode" lang="bash"
+            }
+
+            cmd "deploy" help="Deploy the project" {
+                arg "env" help="Target environment" {
+                    choices "staging" "production"
+                }
+                arg "tags" var=#true help="Deployment tags" var_min=1 var_max=5
+                flag "-f --force" help="Force deploy" deprecated="Use --confirm instead"
+                flag "--confirm" help="Confirm deployment"
+            }
+        "##
+        .parse()
+        .unwrap();
+        spec
+    }
+
+    #[test]
+    fn test_full_feature_types() {
+        let spec = full_feature_spec();
+        let output = super::super::super::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "types.ts"));
+    }
+
+    #[test]
+    fn test_full_feature_client() {
+        let spec = full_feature_spec();
+        let output = super::super::super::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.ts"));
+    }
+
+    /// Spec with config props.
+    #[test]
+    fn test_config_props() {
+        let spec: Spec = r##"
+            bin "myapp"
+            config {
+                prop "debug" default=#true data_type=boolean help="Enable debug mode"
+                prop "port" default=8080 data_type=integer env="MYAPP_PORT"
+                prop "host" data_type=string
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        // just verify it doesn't crash and has the config interface
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("MyappConfig"));
+        assert!(types.contains("debug?: boolean"));
+        assert!(types.contains("port?: number"));
+        assert!(types.contains("host: string"));
+    }
+
+    /// Spec with hyphenated subcommand names.
+    #[test]
+    fn test_hyphenated_subcommands() {
+        let spec: Spec = r##"
+            bin "cli"
+            cmd "add-remote" help="Add a remote" {
+                arg "name"
+                arg "url"
+            }
+            cmd "remove-remote" help="Remove a remote" {
+                arg "name"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.ts"));
+    }
+
+    /// Spec with deeply nested subcommands.
+    #[test]
+    fn test_deep_nesting() {
+        let spec: Spec = r##"
+            bin "app"
+            cmd "db" help="Database operations" {
+                cmd "migration" help="Migration management" {
+                    cmd "create" help="Create a new migration" {
+                        arg "name"
+                        flag "--template <t>" help="Migration template"
+                    }
+                    cmd "run" help="Run pending migrations" {
+                        flag "--step <n>" help="Number of migrations to run"
+                    }
+                }
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.ts"));
+    }
+
+    /// Minimal spec with no args, no flags, no subcommands.
+    #[test]
+    fn test_minimal_spec() {
+        let spec: Spec = r##"
+            bin "hello"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        insta::assert_snapshot!(get_file(&output, "client.ts"));
+    }
+
+    /// Test package_name override.
+    #[test]
+    fn test_package_name_override() {
+        let spec: Spec = r##"
+            bin "original-cli"
+        "##
+        .parse()
+        .unwrap();
+        let opts = SdkOptions {
+            language: SdkLanguage::TypeScript,
+            package_name: Some("MyCustomSdk".to_string()),
+            source_file: None,
+        };
+        let output = super::super::super::generate(&spec, &opts);
+        insta::assert_snapshot!(get_file(&output, "index.ts"));
+    }
+
+    /// Choice type collision: same arg name with different choices in different subcommands.
+    #[test]
+    fn test_choice_collision() {
+        let spec: Spec = r##"
+            bin "tool"
+            cmd "build" help="Build" {
+                arg "env" help="Build environment" {
+                    choices "debug" "release"
+                }
+            }
+            cmd "deploy" help="Deploy" {
+                arg "env" help="Deploy environment" {
+                    choices "staging" "production"
+                }
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("BuildEnvChoice"));
+        assert!(types.contains("DeployEnvChoice"));
+        assert!(types.contains(r#""debug""#));
+        assert!(types.contains(r#""staging""#));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Flags-only subcommand (no positional args).
+    #[test]
+    fn test_flags_only_subcommand() {
+        let spec: Spec = r##"
+            bin "app"
+            cmd "status" help="Show status" {
+                flag "--verbose" help="Show detailed status"
+                flag "--json" help="Output as JSON"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.ts");
+        assert!(client.contains("async exec(flags?: StatusFlags): Promise<CliResult>"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Config with all data_type variants, arg with env, flag with deprecated + aliases,
+    /// reserved keyword identifiers.
+    #[test]
+    fn test_typescript_config_and_flag_edge_cases() {
+        let spec: Spec = r##"
+            bin "myapp"
+            config {
+                prop "debug" default=#true data_type=boolean help="Enable debug mode"
+                prop "port" default=8080 data_type=integer
+                prop "rate" default="1.5" data_type=float
+                prop "host" data_type=string
+                prop "extra" data_type="null"
+            }
+            arg "input" help="Input file" env="MYAPP_INPUT"
+            flag "--type" help="Reserved keyword" deprecated="Use --kind"
+            flag "-f --format --fmt <fmt>" help="Flag with short and long alias"
+            flag "-v" help="Short-only flag"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("MyappConfig"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Hidden command — covers cmd.hide early-return in render_command_types.
+    #[test]
+    fn test_typescript_hidden_command() {
+        let spec: Spec = r##"
+            bin "app"
+            cmd "visible" help="A visible command" {
+                arg "name"
+            }
+            cmd "secret" hide=#true help="Hidden command" {
+                arg "name"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("VisibleArgs"));
+        assert!(!types.contains("SecretArgs"));
+    }
+
+    /// double_dash=automatic, examples with lang, global flags with flags-only subcommand,
+    /// repeatable boolean flag, short-only flag build.
+    #[test]
+    fn test_typescript_client_edge_cases() {
+        let spec: Spec = r##"
+            bin "runner"
+            flag "-v --verbose" global=#true help="Verbosity"
+            flag "--debug" var=#true help="Repeatable boolean flag"
+            arg "input" help="Input file"
+            arg "extra" double_dash="automatic" var=#true help="Extra files"
+            cmd "run" help="Run a task" {
+                example "runner run hello" header="Basic run" lang="bash"
+                arg "task" help="Task to run" double_dash="automatic"
+            }
+            cmd "info" help="Show info" {}
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.ts");
+        assert!(client.contains("double_dash=automatic"));
+        assert!(client.contains("@example Basic run"));
+        assert!(client.contains("```bash"));
+        // GlobalFlags type for info subcommand
+        assert!(client.contains("flags?: GlobalFlags"));
+        // repeatable boolean flag
+        assert!(client.contains("for (const v of flags.debug)"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Args with default values — tests that defaults are preserved, not dropped to undefined.
+    #[test]
+    fn test_typescript_arg_defaults() {
+        let spec: Spec = r##"
+            bin "runner"
+            arg "mode" default="fast" help="Run mode"
+            arg "output" help="Output path" required=#true
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("mode?: string"));
+        assert!(types.contains("output: string"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Optional arg without default and empty flags interface.
+    #[test]
+    fn test_typescript_optional_arg_empty_flags() {
+        let spec: Spec = r##"
+            bin "app"
+            arg "[name]" help="Optional arg without default"
+            cmd "check" help="Check something" {
+                arg "target" required=#true help="Required arg"
+                arg "mode" default="quick" help="Optional arg with default"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("name?: string"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Flag with choices — flag arg with choices renders correct type.
+    #[test]
+    fn test_typescript_flag_with_choices() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "--shell <shell>" help="Shell type" {
+                choices "bash" "zsh" "fish"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains(r#""bash" | "zsh" | "fish""#));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Flag with env annotation — env variable appears in JSDoc.
+    #[test]
+    fn test_typescript_flag_with_env() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "--config <path>" help="Config file" env="APP_CONFIG"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("APP_CONFIG"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Hidden flag excluded from types and client.
+    #[test]
+    fn test_typescript_flag_hide() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "--verbose" help="Verbosity"
+            flag "--debug" hide=#true help="Hidden debug flag"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("verbose"));
+        assert!(!types.contains("debug"));
+    }
+
+    /// Negate flag rendered in client build method.
+    #[test]
+    fn test_typescript_negate_flag_build() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "--dry-run" help="Dry run" negate="--no-dry-run"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.ts");
+        assert!(client.contains("--dry-run"));
+        assert!(client.contains("--no-dry-run"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Count flag rendered in client build method.
+    #[test]
+    fn test_typescript_count_flag_build() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "-v --verbose" count=#true help="Verbosity level"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.ts");
+        assert!(client.contains("-v"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Repeatable value flag with default — covers var + arg + default in client build.
+    #[test]
+    fn test_typescript_var_value_flag_with_default() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "--tag <t>" var=#true default="latest" help="Tags"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("string[]"));
+        let client = get_file(&output, "client.ts");
+        assert!(client.contains("for (const v of flags.tag)"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Flag with multiple long aliases — `-f --format --fmt <fmt>`.
+    #[test]
+    fn test_typescript_multiple_aliases() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "-f --format --fmt <fmt>" help="Output format"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("fmt"));
+        let client = get_file(&output, "client.ts");
+        // should use first long for the flag argument name
+        assert!(client.contains("--format"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Required flag without default — tests non-optional flag type in Flags interface.
+    #[test]
+    fn test_typescript_required_flag_type() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "--token <t>" required=#true help="Auth token"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        // required flag without default should NOT have "?"
+        assert!(types.contains("token: string;"));
+        assert!(!types.contains("token?:"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Global repeatable flags — covers flag_ts_simple var branches in GlobalFlags.
+    #[test]
+    fn test_typescript_global_repeatable_flags() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "-v --verbose" global=#true var=#true help="Repeatable verbose"
+            flag "--tag <t>" global=#true var=#true help="Repeatable tag"
+            cmd "run" help="Run" {
+                arg "target"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        // GlobalFlags should have boolean[] and string[] types
+        assert!(types.contains("boolean[]"));
+        assert!(types.contains("string[]"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Boolean flag with default=#false — covers False default in types.
+    #[test]
+    fn test_typescript_boolean_flag_default_false() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "--no-cache" default=#false help="Disable cache"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("@default false"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Config with all props having defaults — tests Default-friendly rendering.
+    #[test]
+    fn test_typescript_config_all_optional() {
+        let spec: Spec = r##"
+            bin "app"
+            config {
+                prop "debug" default=#true data_type=boolean
+                prop "port" default=8080 data_type=integer
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("AppConfig"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Optional variadic arg — covers the optional + var branch.
+    #[test]
+    fn test_typescript_optional_variadic_arg() {
+        let spec: Spec = r##"
+            bin "tool"
+            arg "[files]" var=#true help="Input files"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("string[]"));
+        let client = get_file(&output, "client.ts");
+        // optional variadic arg should use spread with undefined guard
+        assert!(client.contains("args.files !== undefined"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Boolean config prop with default=#false — covers the false default branch.
+    #[test]
+    fn test_typescript_config_boolean_default_false() {
+        let spec: Spec = r##"
+            bin "app"
+            config {
+                prop "verbose" default=#false data_type=boolean help="Verbose output"
+                prop "dry_run" default=#true data_type=boolean help="Dry run mode"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("verbose?: boolean"));
+        assert!(types.contains("dry_run?: boolean"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// String config prop with default — covers string default branch.
+    #[test]
+    fn test_typescript_config_string_with_default() {
+        let spec: Spec = r##"
+            bin "app"
+            config {
+                prop "host" default="localhost" data_type=string help="Server host"
+                prop "name" default="myapp" data_type=string
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        assert!(types.contains("host?: string"));
+        assert!(types.contains("name?: string"));
+        insta::assert_snapshot!(types);
+    }
+
+    /// Example without lang — covers example rendering without language tag.
+    #[test]
+    fn test_typescript_example_without_lang() {
+        let spec: Spec = r##"
+            bin "app"
+            cmd "greet" help="Greet someone" {
+                example "app greet hello"
+                arg "name" help="Name to greet"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.ts");
+        assert!(client.contains("app greet hello"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Flag edge cases — short-only, deprecated, count with default, value flag with default,
+    /// required flag, repeatable boolean flag.
+    #[test]
+    fn test_typescript_flag_edge_cases() {
+        let spec: Spec = r##"
+            bin "tool"
+            flag "-v" help="Short-only flag"
+            flag "--type" help="Reserved keyword" deprecated="Use --kind"
+            flag "--level" count=#true default="2" help="Count flag with default"
+            flag "--format <fmt>" default="json" help="Value flag with default"
+            flag "--confirm" required=#true help="Required flag"
+            flag "--verbose" var=#true help="Repeatable boolean flag"
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let types = get_file(&output, "types.ts");
+        insta::assert_snapshot!(types);
+        let client = get_file(&output, "client.ts");
+        // short-only flag build
+        assert!(client.contains(r#""-v""#));
+        // repeatable boolean flag build
+        assert!(client.contains("for (const v of flags.verbose)"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// Global flags with flags-only subcommand — covers GlobalFlags type branch.
+    #[test]
+    fn test_typescript_global_flags_flags_only() {
+        let spec: Spec = r##"
+            bin "app"
+            flag "-v --verbose" global=#true help="Verbosity"
+            cmd "status" help="Show status" {
+                flag "--json" help="JSON output"
+            }
+            cmd "info" help="Show info" {}
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.ts");
+        // "info" subcommand has no own flags, only global flags => GlobalFlags type
+        assert!(client.contains("GlobalFlags"));
+        insta::assert_snapshot!(client);
+    }
+
+    /// double_dash=automatic — covers arg ordering and separator insertion.
+    #[test]
+    fn test_typescript_double_dash_automatic() {
+        let spec: Spec = r##"
+            bin "runner"
+            arg "input" help="Input file"
+            arg "extra" double_dash="automatic" var=#true help="Extra files"
+            flag "--verbose" var=#true help="Repeatable boolean flag"
+            cmd "run" help="Run a task" {
+                example "runner run hello" header="Basic run"
+                arg "task" help="Task to run" double_dash="automatic"
+            }
+        "##
+        .parse()
+        .unwrap();
+        let output = super::super::super::generate(&spec, &make_opts());
+        let client = get_file(&output, "client.ts");
+        assert!(client.contains("double_dash=automatic"));
+        insta::assert_snapshot!(client);
+    }
+}
diff --git a/lib/src/sdk/typescript/wrappers.rs b/lib/src/sdk/typescript/wrappers.rs
new file mode 100644
index 00000000..3a391b9a
--- /dev/null
+++ b/lib/src/sdk/typescript/wrappers.rs
@@ -0,0 +1,392 @@
+use heck::AsPascalCase;
+
+use crate::sdk::{
+    collect_choice_types, collect_type_imports, escape_jsdoc, escape_ts_string, generated_header,
+    CodeWriter,
+};
+use crate::spec::arg::SpecDoubleDashChoices;
+use crate::spec::cmd::SpecCommand;
+use crate::{Spec, SpecArg, SpecFlag};
+
+use super::types::{flag_property_name, sanitize_ident};
+
+pub fn render(spec: &Spec, package_name: &str, source_file: &Option<String>) -> String {
+    let mut w = CodeWriter::new();
+
+    w.line(&generated_header("//", source_file));
+    w.line("import { CliRunner, CliResult } from \"./runtime\";");
+
+    // collect all type imports needed
+    let choice_types = collect_choice_types(&spec.cmd);
+    let type_imports = collect_type_imports(&spec.cmd, package_name, &choice_types);
+    let has_global_flags = spec.cmd.flags.iter().any(|f| f.global && !f.hide);
+    if has_global_flags {
+        let mut all_imports = type_imports;
+        all_imports.push("GlobalFlags".to_string());
+        all_imports.sort();
+        all_imports.dedup();
+        w.line(&format!(
+            "import {{ {} }} from \"./types\";",
+            all_imports.join(", ")
+        ));
+    } else if !type_imports.is_empty() {
+        w.line(&format!(
+            "import {{ {} }} from \"./types\";",
+            type_imports.join(", ")
+        ));
+    }
+
+    w.line("");
+
+    // collect root-level global flags for propagation to subcommands
+    let global_flags: Vec<&SpecFlag> = spec
+        .cmd
+        .flags
+        .iter()
+        .filter(|f| f.global && !f.hide)
+        .collect();
+
+    let class_name = AsPascalCase(package_name).to_string();
+
+    // render the root class (the main entry point)
+    render_class(
+        &spec.cmd,
+        &class_name,
+        true,
+        &global_flags,
+        &spec.bin,
+        &mut w,
+    );
+
+    w.finish()
+}
+
+fn subcmd_path(cmd: &SpecCommand) -> String {
+    cmd.full_cmd
+        .iter()
+        .map(|s| format!("\"{}\"", escape_ts_string(s)))
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
+fn render_class(
+    cmd: &SpecCommand,
+    class_name: &str,
+    is_root: bool,
+    global_flags: &[&SpecFlag],
+    bin_name: &str,
+    w: &mut CodeWriter,
+) {
+    let visible_subcmds: Vec<_> = cmd.subcommands.iter().filter(|(_, c)| !c.hide).collect();
+
+    let visible_args: Vec<&SpecArg> = cmd.args.iter().filter(|a| !a.hide).collect();
+    let visible_flags: Vec<&SpecFlag> = cmd.flags.iter().filter(|f| !f.hide).collect();
+    let has_args = !visible_args.is_empty();
+    let has_flags = !visible_flags.is_empty() || !global_flags.is_empty();
+
+    // JSDoc on class
+    let mut class_doc = Vec::new();
+    if let Some(help) = &cmd.help {
+        class_doc.push(help.clone());
+    } else if let Some(about) = &cmd.help_long {
+        class_doc.push(about.clone());
+    }
+    if let Some(deprecated) = &cmd.deprecated {
+        class_doc.push(format!("@deprecated {deprecated}"));
+    }
+    if !cmd.aliases.is_empty() {
+        class_doc.push(format!("Aliases: {}", cmd.aliases.join(", ")));
+    }
+    if !class_doc.is_empty() {
+        let class_doc: Vec<String> = class_doc.iter().map(|s| escape_jsdoc(s)).collect();
+        if class_doc.len() == 1 {
+            w.line(&format!("/** {} */", class_doc[0]));
+        } else {
+            w.line("/**");
+            for line in &class_doc {
+                w.line(&format!(" * {line}"));
+            }
+            w.line(" */");
+        }
+    }
+
+    // class declaration
+    w.line(&format!("export class {class_name} {{"));
+    w.indent();
+
+    // runner field
+    w.line("private runner: CliRunner;");
+
+    // subcommand properties
+    for (name, subcmd) in &visible_subcmds {
+        let sub_class = AsPascalCase(name).to_string();
+        let prop = sanitize_ident(name);
+        let mut doc_parts = Vec::new();
+        if let Some(help) = &subcmd.help {
+            doc_parts.push(help.clone());
+        }
+        if let Some(dep) = &subcmd.deprecated {
+            doc_parts.push(format!("@deprecated {dep}"));
+        }
+        if !doc_parts.is_empty() {
+            w.line(&format!("/** {} */", escape_jsdoc(&doc_parts.join(". "))));
+        }
+        w.line(&format!("readonly {prop}: {sub_class};"));
+    }
+
+    // alias getters for subcommand aliases
+    for (name, subcmd) in &visible_subcmds {
+        for alias in &subcmd.aliases {
+            let alias_prop = sanitize_ident(alias);
+            let target_prop = sanitize_ident(name);
+            let sub_class = AsPascalCase(name).to_string();
+            w.line(&format!("/** Alias for `{}` */", escape_jsdoc(name)));
+            w.line(&format!(
+                "get {alias_prop}(): {sub_class} {{ return this.{target_prop}; }}"
+            ));
+        }
+    }
+
+    // constructor
+    w.line("");
+    if is_root {
+        w.line("constructor(binPath?: string) {");
+        w.indent();
+        w.line(&format!(
+            "this.runner = new CliRunner(binPath ?? \"{}\");",
+            escape_ts_string(bin_name)
+        ));
+    } else {
+        w.line("constructor(runner: CliRunner) {");
+        w.indent();
+        w.line("this.runner = runner;");
+    }
+    for (name, _) in &visible_subcmds {
+        let sub_class = AsPascalCase(name).to_string();
+        let prop = sanitize_ident(name);
+        w.line(&format!("this.{prop} = new {sub_class}(this.runner);"));
+    }
+    w.dedent();
+    w.line("}");
+
+    // exec method
+    let args_param = if has_args {
+        format!("args: {class_name}Args")
+    } else {
+        String::new()
+    };
+    let flags_type = if !global_flags.is_empty() && !visible_flags.is_empty() {
+        format!("{class_name}Flags")
+    } else if !global_flags.is_empty() && visible_flags.is_empty() {
+        "GlobalFlags".to_string()
+    } else if !visible_flags.is_empty() {
+        format!("{class_name}Flags")
+    } else {
+        String::new()
+    };
+    let flags_param = if !flags_type.is_empty() {
+        if has_args {
+            format!(", flags?: {flags_type}")
+        } else {
+            format!("flags?: {flags_type}")
+        }
+    } else {
+        String::new()
+    };
+
+    // JSDoc on exec
+    let mut exec_doc = Vec::new();
+    if !cmd.usage.is_empty() {
+        exec_doc.push(cmd.usage.clone());
+    }
+    for example in &cmd.examples {
+        let label = example.header.as_deref().unwrap_or("Example");
+        let lang = if example.lang.is_empty() {
+            ""
+        } else {
+            &example.lang
+        };
+        exec_doc.push(format!(
+            "@example {label}\n```{lang}\n{code}\n```",
+            code = example.code
+        ));
+    }
+    if !exec_doc.is_empty() {
+        let exec_doc: Vec<String> = exec_doc.iter().map(|s| escape_jsdoc(s)).collect();
+        if exec_doc.len() == 1 && !exec_doc[0].contains('\n') {
+            w.line(&format!("/** {} */", exec_doc[0]));
+        } else {
+            w.line("/**");
+            for part in &exec_doc {
+                for line in part.split('\n') {
+                    w.line(&format!(" * {line}"));
+                }
+            }
+            w.line(" */");
+        }
+    }
+
+    if has_args || has_flags {
+        w.line(&format!(
+            "async exec({args_param}{flags_param}): Promise<CliResult> {{"
+        ));
+        w.indent();
+
+        // build command args
+        let path = subcmd_path(cmd);
+        w.line(&format!("const cmdArgs: string[] = [{path}];"));
+
+        // add positional args with double_dash handling
+        if has_args {
+            let has_required_double_dash = visible_args
+                .iter()
+                .any(|a| matches!(a.double_dash, SpecDoubleDashChoices::Required));
+            let has_automatic_double_dash = visible_args
+                .iter()
+                .any(|a| matches!(a.double_dash, SpecDoubleDashChoices::Automatic));
+
+            // Args before `--`: all args without double_dash=required
+            for arg in &visible_args {
+                if matches!(arg.double_dash, SpecDoubleDashChoices::Required) {
+                    continue;
+                }
+                let ident = sanitize_ident(&arg.name);
+                if arg.var {
+                    w.line(&format!(
+                        "if (args.{ident} !== undefined) {{ cmdArgs.push(...args.{ident}); }}"
+                    ));
+                } else {
+                    w.line(&format!(
+                        "if (args.{ident} !== undefined) {{ cmdArgs.push(String(args.{ident})); }}"
+                    ));
+                }
+            }
+
+            if has_required_double_dash {
+                w.line("cmdArgs.push(\"--\");");
+                // Args after `--`: only double_dash=required args
+                for arg in &visible_args {
+                    if !matches!(arg.double_dash, SpecDoubleDashChoices::Required) {
+                        continue;
+                    }
+                    let ident = sanitize_ident(&arg.name);
+                    if arg.var {
+                        w.line(&format!(
+                            "if (args.{ident} !== undefined) {{ cmdArgs.push(...args.{ident}); }}"
+                        ));
+                    } else {
+                        w.line(&format!(
+                            "if (args.{ident} !== undefined) {{ cmdArgs.push(String(args.{ident})); }}"
+                        ));
+                    }
+                }
+            } else if has_automatic_double_dash {
+                w.line(
+                    "// double_dash=automatic: \"--\" is implied after the first positional arg",
+                );
+            }
+        }
+
+        // add flags
+        if has_flags {
+            w.line("const flagArgs = this.buildFlagArgs(flags);");
+            w.line("return this.runner.run([...cmdArgs, ...flagArgs]);");
+        } else {
+            w.line("return this.runner.run(cmdArgs);");
+        }
+
+        w.dedent();
+        w.line("}");
+
+        // buildFlagArgs method
+        if has_flags {
+            w.line("");
+            w.line(&format!(
+                "private buildFlagArgs(flags?: {flags_type}): string[] {{"
+            ));
+            w.indent();
+            w.line("const result: string[] = [];");
+            w.line("if (!flags) return result;");
+
+            for flag in global_flags {
+                render_flag_build(flag, w);
+            }
+            for flag in &visible_flags {
+                if !global_flags.iter().any(|gf| gf.name == flag.name) {
+                    render_flag_build(flag, w);
+                }
+            }
+
+            w.line("return result;");
+            w.dedent();
+            w.line("}");
+        }
+    } else {
+        // no args/flags: provide a simple exec
+        w.line("async exec(): Promise<CliResult> {");
+        w.indent();
+        let path = subcmd_path(cmd);
+        w.line(&format!("return this.runner.run([{path}]);"));
+        w.dedent();
+        w.line("}");
+    }
+
+    w.dedent();
+    w.line("}");
+
+    // render subcommand classes
+    for (name, subcmd) in &visible_subcmds {
+        w.line("");
+        let sub_class = AsPascalCase(name).to_string();
+        render_class(subcmd, &sub_class, false, global_flags, bin_name, w);
+    }
+}
+
+fn render_flag_build(flag: &SpecFlag, w: &mut CodeWriter) {
+    let prop_name = flag_property_name(flag);
+
+    // use the first long name for the flag argument, or short if no long
+    let flag_arg_name = if let Some(long) = flag.long.first() {
+        format!("--{}", escape_ts_string(long))
+    } else if let Some(short) = flag.short.first() {
+        format!("-{short}")
+    } else {
+        format!("--{}", escape_ts_string(&flag.name))
+    };
+
+    if flag.arg.is_some() {
+        if flag.var {
+            // repeatable value flag: --flag val1 --flag val2
+            w.line(&format!(
+                "if (flags.{prop_name} !== undefined) {{ for (const v of flags.{prop_name}) {{ result.push(\"{flag_arg_name}\", String(v)); }} }}"
+            ));
+        } else {
+            // single value flag
+            w.line(&format!(
+                "if (flags.{prop_name} !== undefined) {{ result.push(\"{flag_arg_name}\", String(flags.{prop_name})); }}"
+            ));
+        }
+    } else if flag.count {
+        w.line(&format!(
+            "if (flags.{prop_name} !== undefined && flags.{prop_name} > 0) {{ for (let i = 0; i < flags.{prop_name}; i++) {{ result.push(\"{flag_arg_name}\"); }} }}"
+        ));
+    } else if flag.var {
+        // repeatable boolean flag
+        w.line(&format!(
+            "if (flags.{prop_name} !== undefined) {{ for (const v of flags.{prop_name}) {{ if (v) result.push(\"{flag_arg_name}\"); }} }}"
+        ));
+    } else {
+        // boolean flag
+        w.line(&format!(
+            "if (flags.{prop_name}) {{ result.push(\"{flag_arg_name}\"); }}"
+        ));
+
+        // handle negate
+        if let Some(negate) = &flag.negate {
+            w.line(&format!(
+                "else if (flags.{prop_name} === false) {{ result.push(\"{}\"); }}",
+                escape_ts_string(negate)
+            ));
+        }
+    }
+}
diff --git a/lib/src/spec/mod.rs b/lib/src/spec/mod.rs
index f5563605..56a90a42 100644
--- a/lib/src/spec/mod.rs
+++ b/lib/src/spec/mod.rs
@@ -5,7 +5,7 @@ pub mod cmd;
 pub mod complete;
 pub mod config;
 mod context;
-mod data_types;
+pub mod data_types;
 pub mod flag;
 pub mod helpers;
 pub mod mount;
diff --git a/lib/tests/sdk_compile.rs b/lib/tests/sdk_compile.rs
new file mode 100644
index 00000000..a7f005ce
--- /dev/null
+++ b/lib/tests/sdk_compile.rs
@@ -0,0 +1,216 @@
+use std::fs;
+use std::path::Path;
+use std::process::Command;
+
+use usage::sdk::{SdkLanguage, SdkOptions, SdkOutput};
+use usage::Spec;
+
+/// Comprehensive spec that exercises all SDK features:
+/// version, about, author, global flags, choices, deprecated, aliases,
+/// examples, double_dash, var args, negate flags, config props,
+/// repeatable boolean flags, numeric choices.
+fn full_spec() -> Spec {
+    r##"
+        bin "mytool"
+        name "mytool"
+        version "1.2.3"
+        about "A powerful CLI tool"
+        author "Jane Doe"
+
+        config {
+            prop "debug" default=#true data_type=boolean help="Enable debug mode"
+            prop "port" default=8080 data_type=integer help="Port number"
+            prop "rate" default="1.5" data_type=float help="Rate limit"
+            prop "host" data_type=string help="Host address"
+        }
+
+        flag "-v --verbose" help="Verbosity level" count=#true global=#true
+        flag "-C --config <path>" help="Config file path" global=#true env="MYTOOL_CONFIG"
+        flag "--dry-run" help="Show what would be done" negate="--no-dry-run"
+        flag "--debug" var=#true help="Repeatable boolean flag"
+
+        arg "input" help="Input file" required=#true
+        arg "[extra]" var=#true help="Extra files"
+
+        cmd "build" help="Build the project" deprecated="Use compile instead" {
+            alias "b"
+            arg "target" help="Build target" {
+                choices "debug" "release"
+            }
+            arg "output" help="Output directory" double_dash="required"
+            flag "-j --jobs <n>" help="Parallel jobs" var=#true
+            flag "--release" help="Build in release mode"
+            example "mytool build --release target" header="Build in release mode" lang="bash"
+        }
+
+        cmd "deploy" help="Deploy the project" {
+            arg "env" help="Target environment" {
+                choices "staging" "production"
+            }
+            arg "tags" var=#true help="Deployment tags" var_min=1 var_max=5
+            flag "-f --force" help="Force deploy" deprecated="Use --confirm instead"
+            flag "--confirm" help="Confirm deployment"
+        }
+
+        cmd "log" help="Show log level" {
+            arg "level" help="Log level" {
+                choices "1" "2" "3" "4" "5"
+            }
+            flag "--json" help="Output as JSON"
+        }
+
+        cmd "status" help="Show status" {
+            flag "--json" help="Output as JSON"
+        }
+    "##
+    .parse()
+    .unwrap()
+}
+
+fn write_sdk_to_dir(output: &SdkOutput, dir: &Path) {
+    for file in &output.files {
+        let path = dir.join(&file.path);
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent).unwrap();
+        }
+        fs::write(&path, &file.content).unwrap();
+    }
+}
+
+fn tool_exists(name: &str) -> bool {
+    Command::new(name).arg("--version").output().is_ok()
+}
+
+fn npx_tsc_available() -> bool {
+    Command::new("npx")
+        .args(["--yes", "typescript", "tsc", "--version"])
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false)
+}
+
+// ---------------------------------------------------------------------------
+// Python
+// ---------------------------------------------------------------------------
+
+#[test]
+fn test_python_sdk_imports() {
+    if !tool_exists("python3") {
+        eprintln!("Skipping Python SDK import test - python3 not found");
+        return;
+    }
+
+    let spec = full_spec();
+    let output = usage::sdk::generate(
+        &spec,
+        &SdkOptions {
+            language: SdkLanguage::Python,
+            package_name: None,
+            source_file: None,
+        },
+    );
+
+    let dir = tempfile::tempdir().unwrap();
+    // Python files are flat in the package directory
+    let pkg_dir = dir.path().join("mytool_sdk");
+    fs::create_dir_all(&pkg_dir).unwrap();
+    write_sdk_to_dir(&output, &pkg_dir);
+
+    // Validate syntax + imports for each module
+    for module in &["types", "client", "runtime"] {
+        let result = Command::new("python3")
+            .args([
+                "-c",
+                &format!(
+                    "import sys; sys.path.insert(0, '{}'); from mytool_sdk.{module} import *",
+                    dir.path().display()
+                ),
+            ])
+            .output()
+            .expect("Failed to run python3");
+
+        if !result.status.success() {
+            let stderr = String::from_utf8_lossy(&result.stderr);
+            panic!("Generated Python SDK {module}.py has errors:\n{stderr}");
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// TypeScript
+// ---------------------------------------------------------------------------
+
+#[test]
+fn test_typescript_sdk_typechecks() {
+    if !npx_tsc_available() {
+        eprintln!("Skipping TypeScript SDK typecheck test - tsc not available via npx");
+        return;
+    }
+
+    let spec = full_spec();
+    let output = usage::sdk::generate(
+        &spec,
+        &SdkOptions {
+            language: SdkLanguage::TypeScript,
+            package_name: None,
+            source_file: None,
+        },
+    );
+
+    let dir = tempfile::tempdir().unwrap();
+    write_sdk_to_dir(&output, dir.path());
+
+    // Install @types/node for Node.js type declarations
+    if !tool_exists("npm") {
+        eprintln!("Skipping TypeScript SDK typecheck test - npm not found");
+        return;
+    }
+
+    let npm_result = Command::new("npm")
+        .args(["init", "-y", "--scope=sdk-test"])
+        .current_dir(dir.path())
+        .output()
+        .expect("Failed to run npm init");
+    if !npm_result.status.success() {
+        let stderr = String::from_utf8_lossy(&npm_result.stderr);
+        panic!("npm init failed:\n{stderr}");
+    }
+
+    let npm_result = Command::new("npm")
+        .args(["install", "@types/node"])
+        .current_dir(dir.path())
+        .output()
+        .expect("Failed to install @types/node");
+    if !npm_result.status.success() {
+        let stderr = String::from_utf8_lossy(&npm_result.stderr);
+        panic!("npm install @types/node failed:\n{stderr}");
+    }
+
+    // Write tsconfig.json referencing @types/node
+    let tsconfig = r#"{
+        "compilerOptions": {
+            "target": "ES2020",
+            "module": "ES2020",
+            "moduleResolution": "bundler",
+            "strict": true,
+            "noEmit": true,
+            "skipLibCheck": true,
+            "esModuleInterop": true,
+            "types": ["node"]
+        },
+        "include": ["./*.ts"]
+    }"#;
+    fs::write(dir.path().join("tsconfig.json"), tsconfig).unwrap();
+
+    let result = Command::new("npx")
+        .args(["--yes", "typescript", "tsc", "--project"])
+        .arg(dir.path().join("tsconfig.json"))
+        .output()
+        .expect("Failed to run tsc");
+
+    if !result.status.success() {
+        let stdout = String::from_utf8_lossy(&result.stdout);
+        let stderr = String::from_utf8_lossy(&result.stderr);
+        panic!("Generated TypeScript SDK does not typecheck:\nstdout: {stdout}\nstderr: {stderr}");
+    }
+}
diff --git a/mise.lock b/mise.lock
index 3c8901ed..9b2d5eea 100644
--- a/mise.lock
+++ b/mise.lock
@@ -1,4 +1,4 @@
-# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
+# @generated - this file is auto-generated by `mise lock` https://mise.en.dev/dev-tools/mise-lock.html
 
 [[tools.actionlint]]
 version = "1.7.10"
@@ -228,6 +228,10 @@ url = "https://nodejs.org/dist/v24.14.0/node-v24.14.0-win-x64.zip"
 version = "3.8.1"
 backend = "npm:prettier"
 
+[[tools."npm:tsc"]]
+version = "2.0.4"
+backend = "npm:tsc"
+
 [[tools.pnpm]]
 version = "10.29.3"
 backend = "aqua:pnpm/pnpm"
@@ -240,6 +244,45 @@ url = "https://github.com/pnpm/pnpm/releases/download/v10.29.3/pnpm-linux-x64"
 checksum = "sha256:a248c56b0ab20443e18d0c8ee3207c6c564ee342bd3fc8694b3569a060cecece"
 url = "https://github.com/pnpm/pnpm/releases/download/v10.29.3/pnpm-macos-arm64"
 
+[[tools.python]]
+version = "3.14.4"
+backend = "core:python"
+
+[tools.python."platforms.linux-arm64"]
+checksum = "sha256:b8b597fdb2f8dccdc502c11947b60a4b65eb6bce79cfa60c7ccf9b6e8352c60a"
+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/cpython-3.14.4+20260414-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz"
+provenance = "github-attestations"
+
+[tools.python."platforms.linux-arm64-musl"]
+checksum = "sha256:a10687b226e0941632569836bc1d8fa6353a8e3e8424316467ca9cdf220b983d"
+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/cpython-3.14.4+20260414-aarch64-unknown-linux-musl-install_only_stripped.tar.gz"
+provenance = "github-attestations"
+
+[tools.python."platforms.linux-x64"]
+checksum = "sha256:fe9a9c32d13870af632cbac3dfc7528ae53597e94472aa4c7d6a42e8166136cd"
+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/cpython-3.14.4+20260414-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"
+provenance = "github-attestations"
+
+[tools.python."platforms.linux-x64-musl"]
+checksum = "sha256:d6005226cd24e780630626232c7a63243d4885fdf975dcf930a0758a0759ce14"
+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/cpython-3.14.4+20260414-x86_64-unknown-linux-musl-install_only_stripped.tar.gz"
+provenance = "github-attestations"
+
+[tools.python."platforms.macos-arm64"]
+checksum = "blake3:0314ec66e0f33ec04959583b5900bc8edae371a396aa96b8874e750d1fe936e6"
+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/cpython-3.14.4+20260414-aarch64-apple-darwin-install_only_stripped.tar.gz"
+provenance = "github-attestations"
+
+[tools.python."platforms.macos-x64"]
+checksum = "sha256:d51250a32fa5d9f0799c7bcb71720c27b10a3afd4a7de288120f96085d508a5a"
+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/cpython-3.14.4+20260414-x86_64-apple-darwin-install_only_stripped.tar.gz"
+provenance = "github-attestations"
+
+[tools.python."platforms.windows-x64"]
+checksum = "sha256:a976991dcd085c1bb5d9a8084823a6bc8b7f9b079d8c432574a6ddd68c3a6fe1"
+url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260414/cpython-3.14.4+20260414-x86_64-pc-windows-msvc-install_only_stripped.tar.gz"
+provenance = "github-attestations"
+
 [[tools.shellcheck]]
 version = "0.11.0"
 backend = "aqua:koalaman/shellcheck"
diff --git a/mise.toml b/mise.toml
index 3ca21a34..50b7b921 100644
--- a/mise.toml
+++ b/mise.toml
@@ -16,6 +16,8 @@ gh = "latest"
 "npm:prettier" = "latest"
 shellcheck = "latest"
 node = "24"
+python = "latest"
+"npm:tsc" = "latest"
 
 [tasks.autofix]
 depends = ["render", "lint-fix", "snapshots"]