From a3d8ca2f90ab1e7be708d21f70ff8370aa2380b0 Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Mon, 9 Dec 2024 10:16:13 -0600
Subject: [PATCH] feat: `usage g json` (#184)

---
 cli/src/cli/generate/json.rs                  |  26 +
 cli/src/cli/generate/mod.rs                   |   5 +-
 cli/usage.usage.kdl                           |   8 +
 docs/.vitepress/config.mts                    |  21 +-
 docs/cli/bash.md                              |  26 +
 docs/cli/complete-word.md                     |  33 ++
 docs/cli/generate.md                          |  12 +
 docs/cli/generate/completion.md               |  33 ++
 docs/cli/generate/fig.md                      |  18 +
 docs/cli/generate/json.md                     |  16 +
 docs/cli/generate/markdown.md                 |  29 +
 docs/cli/reference.md                         | 189 -------
 docs/cli/reference/bash.md                    |  30 +
 docs/cli/reference/commands.json              | 527 ++++++++++++++++++
 docs/cli/reference/complete-word.md           |  33 ++
 docs/cli/reference/generate.md                |  12 +
 docs/cli/reference/generate/completion.md     |  33 ++
 docs/cli/reference/generate/fig.md            |  18 +
 docs/cli/reference/generate/json.md           |  16 +
 docs/cli/reference/generate/markdown.md       |  29 +
 docs/cli/reference/index.md                   |  29 +
 examples/docs/MISE_INLINE.md                  |   4 +
 examples/docs/MISE_MULTI.md                   |   4 +
 .../markdown/templates/arg_template.md.tera   |   2 +-
 .../markdown/templates/cmd_template.md.tera   |   8 +-
 .../markdown/templates/flag_template.md.tera  |   2 +-
 .../markdown/templates/spec_template.md.tera  |   2 +-
 lib/src/spec/arg.rs                           |  10 +
 lib/src/spec/cmd.rs                           |  12 +
 lib/src/spec/complete.rs                      |   2 +
 lib/src/spec/flag.rs                          |  12 +
 lib/src/spec/mod.rs                           |  18 +
 mise.toml                                     |   5 +-
 33 files changed, 1025 insertions(+), 199 deletions(-)
 create mode 100644 cli/src/cli/generate/json.rs
 create mode 100644 docs/cli/bash.md
 create mode 100644 docs/cli/complete-word.md
 create mode 100644 docs/cli/generate.md
 create mode 100644 docs/cli/generate/completion.md
 create mode 100644 docs/cli/generate/fig.md
 create mode 100644 docs/cli/generate/json.md
 create mode 100644 docs/cli/generate/markdown.md
 delete mode 100644 docs/cli/reference.md
 create mode 100644 docs/cli/reference/bash.md
 create mode 100644 docs/cli/reference/commands.json
 create mode 100644 docs/cli/reference/complete-word.md
 create mode 100644 docs/cli/reference/generate.md
 create mode 100644 docs/cli/reference/generate/completion.md
 create mode 100644 docs/cli/reference/generate/fig.md
 create mode 100644 docs/cli/reference/generate/json.md
 create mode 100644 docs/cli/reference/generate/markdown.md
 create mode 100644 docs/cli/reference/index.md

diff --git a/cli/src/cli/generate/json.rs b/cli/src/cli/generate/json.rs
new file mode 100644
index 0000000..5e383c6
--- /dev/null
+++ b/cli/src/cli/generate/json.rs
@@ -0,0 +1,26 @@
+use crate::cli::generate;
+use crate::Result;
+use miette::IntoDiagnostic;
+use std::path::PathBuf;
+
+/// Outputs a usage spec in json format
+#[derive(clap::Args)]
+#[clap()]
+pub struct Json {
+    /// A usage spec taken in as a file
+    #[clap(short, long)]
+    file: Option<PathBuf>,
+
+    /// raw string spec input
+    #[clap(long, required_unless_present = "file", overrides_with = "file")]
+    spec: Option<String>,
+}
+
+impl Json {
+    pub fn run(&self) -> Result<()> {
+        let spec = generate::file_or_spec(&self.file, &self.spec)?;
+        let json = serde_json::to_string_pretty(&spec).into_diagnostic()?;
+        println!("{json}");
+        Ok(())
+    }
+}
diff --git a/cli/src/cli/generate/mod.rs b/cli/src/cli/generate/mod.rs
index 54673f9..5ff6473 100644
--- a/cli/src/cli/generate/mod.rs
+++ b/cli/src/cli/generate/mod.rs
@@ -5,6 +5,7 @@ use usage::Spec;
 
 mod completion;
 mod fig;
+mod json;
 mod markdown;
 
 #[derive(clap::Args)]
@@ -18,6 +19,7 @@ pub struct Generate {
 pub enum Command {
     Completion(completion::Completion),
     Fig(fig::Fig),
+    Json(json::Json),
     Markdown(markdown::Markdown),
 }
 
@@ -25,8 +27,9 @@ impl Generate {
     pub fn run(&self) -> miette::Result<()> {
         match &self.command {
             Command::Completion(cmd) => cmd.run(),
-            Command::Markdown(cmd) => cmd.run(),
             Command::Fig(cmd) => cmd.run(),
+            Command::Json(cmd) => cmd.run(),
+            Command::Markdown(cmd) => cmd.run(),
         }
     }
 }
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index c20aee6..e0f1f60 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -68,6 +68,14 @@ cmd "generate" subcommand_required=true {
             arg "<OUT_FILE>"
         }
     }
+    cmd "json" help="Outputs a usage spec in json format" {
+        flag "-f --file" help="A usage spec taken in as a file" {
+            arg "<FILE>"
+        }
+        flag "--spec" help="raw string spec input" {
+            arg "<SPEC>"
+        }
+    }
     cmd "markdown" {
         alias "md"
         flag "-f --file" help="A usage spec taken in as a file" required=true {
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index bb0fe0e..cff0de1 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -1,4 +1,17 @@
 import { defineConfig } from "vitepress";
+import spec from "../cli/reference/commands.json";
+
+function getCommands(cmd): string[][] {
+  const commands = [];
+  for (const [name, sub] of Object.entries(cmd.subcommands)) {
+    if (sub.hide) continue;
+    commands.push(sub.full_cmd);
+    commands.push(...getCommands(sub));
+  }
+  return commands;
+}
+
+const commands = getCommands(spec.cmd);
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -31,7 +44,13 @@ export default defineConfig({
           { text: "Manpages", link: "/cli/manpages" },
           { text: "Markdown", link: "/cli/markdown" },
           { text: "Scripts", link: "/cli/scripts" },
-          { text: "CLI Reference", link: "/cli/reference" }
+          {
+            text: "CLI Reference", link: "/cli/reference/", items:
+              commands.map((command) => ({
+                text: command.join(" "),
+                link: `/cli/reference/${command.join("/")}`
+              }))
+          }
         ]
       },
       {
diff --git a/docs/cli/bash.md b/docs/cli/bash.md
new file mode 100644
index 0000000..4c99418
--- /dev/null
+++ b/docs/cli/bash.md
@@ -0,0 +1,26 @@
+# `usage bash`
+
+- **Usage**: `usage bash [-h] [--help] <SCRIPT> [ARGS]...`
+- **Source code**: [`cli/src/cli/bash.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/bash.rs)
+
+Executes a bash script
+
+Typically, this will be called by a script's shebang
+
+## Arguments
+
+### `<SCRIPT>`
+
+### `[ARGS]...`
+
+arguments to pass to script
+
+## Flags
+
+### `-h`
+
+show help
+
+### `--help`
+
+show help
diff --git a/docs/cli/complete-word.md b/docs/cli/complete-word.md
new file mode 100644
index 0000000..1fd50ce
--- /dev/null
+++ b/docs/cli/complete-word.md
@@ -0,0 +1,33 @@
+# `usage complete-word`
+
+- **Usage**: `usage complete-word [FLAGS] [WORDS]...`
+- **Aliases**: `cw`
+- **Source code**: [`cli/src/cli/complete-word.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/complete-word.rs)
+
+## Arguments
+
+### `[WORDS]...`
+
+user's input from the command line
+
+## Flags
+
+### `--shell <SHELL>`
+
+**Choices:**
+
+- `bash`
+- `fish`
+- `zsh`
+
+### `-f --file <FILE>`
+
+usage spec file or script with usage shebang
+
+### `-s --spec <SPEC>`
+
+raw string spec input
+
+### `--cword <CWORD>`
+
+current word index
diff --git a/docs/cli/generate.md b/docs/cli/generate.md
new file mode 100644
index 0000000..7025033
--- /dev/null
+++ b/docs/cli/generate.md
@@ -0,0 +1,12 @@
+# `usage generate`
+
+- **Usage**: `usage generate <SUBCOMMAND>`
+- **Aliases**: `g`
+- **Source code**: [`cli/src/cli/generate.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate.rs)
+
+## Subcommands
+
+- [`usage generate completion [FLAGS] <SHELL> <BIN>`](/generate/completion.md)
+- [`usage generate fig [FLAGS]`](/generate/fig.md)
+- [`usage generate json [-f --file <FILE>] [--spec <SPEC>]`](/generate/json.md)
+- [`usage generate markdown <FLAGS>`](/generate/markdown.md)
diff --git a/docs/cli/generate/completion.md b/docs/cli/generate/completion.md
new file mode 100644
index 0000000..7a33c1b
--- /dev/null
+++ b/docs/cli/generate/completion.md
@@ -0,0 +1,33 @@
+# `usage generate completion`
+
+- **Usage**: `usage generate completion [FLAGS] <SHELL> <BIN>`
+- **Aliases**: `c`
+- **Source code**: [`cli/src/cli/generate/completion.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/completion.rs)
+
+## Arguments
+
+### `<SHELL>`
+
+**Choices:**
+
+- `bash`
+- `fish`
+- `zsh`
+
+### `<BIN>`
+
+The CLI which we're generates completions for
+
+## Flags
+
+### `--cache-key <CACHE_KEY>`
+
+A cache key to use for storing the results of calling the CLI with --usage-cmd
+
+### `-f --file <FILE>`
+
+A .usage.kdl spec file to use for generating completions
+
+### `--usage-cmd <USAGE_CMD>`
+
+A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to "$bin --usage"
diff --git a/docs/cli/generate/fig.md b/docs/cli/generate/fig.md
new file mode 100644
index 0000000..b2dbbb3
--- /dev/null
+++ b/docs/cli/generate/fig.md
@@ -0,0 +1,18 @@
+# `usage generate fig`
+
+- **Usage**: `usage generate fig [FLAGS]`
+- **Source code**: [`cli/src/cli/generate/fig.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/fig.rs)
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `--spec <SPEC>`
+
+raw string spec input
+
+### `--out-file <OUT_FILE>`
+
+File on where to save the generated Fig spec
diff --git a/docs/cli/generate/json.md b/docs/cli/generate/json.md
new file mode 100644
index 0000000..fa8bd19
--- /dev/null
+++ b/docs/cli/generate/json.md
@@ -0,0 +1,16 @@
+# `usage generate json`
+
+- **Usage**: `usage generate json [-f --file <FILE>] [--spec <SPEC>]`
+- **Source code**: [`cli/src/cli/generate/json.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/json.rs)
+
+Outputs a usage spec in json format
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `--spec <SPEC>`
+
+raw string spec input
diff --git a/docs/cli/generate/markdown.md b/docs/cli/generate/markdown.md
new file mode 100644
index 0000000..364e8c3
--- /dev/null
+++ b/docs/cli/generate/markdown.md
@@ -0,0 +1,29 @@
+# `usage generate markdown`
+
+- **Usage**: `usage generate markdown <FLAGS>`
+- **Aliases**: `md`
+- **Source code**: [`cli/src/cli/generate/markdown.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/markdown.rs)
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `-m --multi`
+
+Render each subcommand as a separate markdown file
+
+### `--url-prefix <URL_PREFIX>`
+
+Prefix to add to all URLs
+
+### `--html-encode`
+
+Escape HTML in markdown
+
+### `--out-dir <OUT_DIR>`
+
+Output markdown files to this directory
+
+### `--out-file <OUT_FILE>`
diff --git a/docs/cli/reference.md b/docs/cli/reference.md
deleted file mode 100644
index ab69b0b..0000000
--- a/docs/cli/reference.md
+++ /dev/null
@@ -1,189 +0,0 @@
-# `usage`
-- **version**: 1.3.5
-
-CLI for working with usage-based CLIs
-
-
-- **Usage**: `usage [--usage-spec] [COMPLETIONS] <SUBCOMMAND>`
-
-## Arguments
-
-### `[COMPLETIONS]`
-
-Outputs completions for the specified shell for completing the `usage` CLI itself
-
-## Flags
-
-### `--usage-spec`
-
-Outputs a `usage.kdl` spec for this CLI itself
-
-## `usage bash`
-
-- **Usage**: `usage bash [-h] [--help] <SCRIPT> [ARGS]...`
-- **Source code**: [`cli/src/cli/bash.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/bash.rs)
-
-Executes a bash script
-
-Typically, this will be called by a script's shebang
-
-### Arguments
-
-#### `<SCRIPT>`
-
-#### `[ARGS]...`
-
-arguments to pass to script
-
-### Flags
-
-#### `-h`
-
-show help
-
-#### `--help`
-
-show help
-
-## `usage complete-word`
-
-- **Usage**: `usage complete-word [FLAGS] [WORDS]...`
-- **Aliases**: `cw`
-- **Source code**: [`cli/src/cli/complete-word.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/complete-word.rs)
-
-### Arguments
-
-#### `[WORDS]...`
-
-user's input from the command line
-
-### Flags
-
-#### `--shell <SHELL>`
-
-**Choices:**
-
-- `bash`
-- `fish`
-- `zsh`
-
-#### `-f --file <FILE>`
-
-usage spec file or script with usage shebang
-
-#### `-s --spec <SPEC>`
-
-raw string spec input
-
-#### `--cword <CWORD>`
-
-current word index
-
-## `usage exec`
-
-- **Usage**: `usage exec <ARGS>…`
-- **Aliases**: `x`
-- **Source code**: [`cli/src/cli/exec.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/exec.rs)
-
-### Arguments
-
-#### `<COMMAND>`
-
-command to execute after parsing usage spec
-
-#### `<BIN>`
-
-path to script to execute
-
-#### `[ARGS]...`
-
-arguments to pass to script
-
-## `usage generate`
-
-- **Usage**: `usage generate <SUBCOMMAND>`
-- **Aliases**: `g`
-- **Source code**: [`cli/src/cli/generate.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate.rs)
-
-## `usage generate completion`
-
-- **Usage**: `usage generate completion [FLAGS] <SHELL> <BIN>`
-- **Aliases**: `c`
-- **Source code**: [`cli/src/cli/generate/completion.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/completion.rs)
-
-### Arguments
-
-#### `<SHELL>`
-
-**Choices:**
-
-- `bash`
-- `fish`
-- `zsh`
-
-#### `<BIN>`
-
-The CLI which we're generates completions for
-
-### Flags
-
-#### `--cache-key <CACHE_KEY>`
-
-A cache key to use for storing the results of calling the CLI with --usage-cmd
-
-#### `-f --file <FILE>`
-
-A .usage.kdl spec file to use for generating completions
-
-#### `--usage-cmd <USAGE_CMD>`
-
-A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to "$bin --usage"
-
-## `usage generate fig`
-
-- **Usage**: `usage generate fig [FLAGS]`
-- **Source code**: [`cli/src/cli/generate/fig.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/fig.rs)
-
-### Flags
-
-#### `-f --file <FILE>`
-
-A usage spec taken in as a file
-
-#### `--spec <SPEC>`
-
-raw string spec input
-
-#### `--out-file <OUT_FILE>`
-
-File on where to save the generated Fig spec
-
-## `usage generate markdown`
-
-- **Usage**: `usage generate markdown <FLAGS>`
-- **Aliases**: `md`
-- **Source code**: [`cli/src/cli/generate/markdown.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/markdown.rs)
-
-### Flags
-
-#### `-f --file <FILE>`
-
-A usage spec taken in as a file
-
-#### `-m --multi`
-
-Render each subcommand as a separate markdown file
-
-#### `--url-prefix <URL_PREFIX>`
-
-Prefix to add to all URLs
-
-#### `--html-encode`
-
-Escape HTML in markdown
-
-#### `--out-dir <OUT_DIR>`
-
-Output markdown files to this directory
-
-#### `--out-file <OUT_FILE>`
diff --git a/docs/cli/reference/bash.md b/docs/cli/reference/bash.md
new file mode 100644
index 0000000..4025a93
--- /dev/null
+++ b/docs/cli/reference/bash.md
@@ -0,0 +1,30 @@
+# `usage bash`
+
+- **Usage**: `usage bash [-h] [--help] <SCRIPT> [ARGS]...`
+- **Source code**: [`cli/src/cli/bash.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/bash.rs)
+
+Executes a bash script
+
+Typically, this will be called by a script's shebang
+
+## Arguments
+
+### `<SCRIPT>`
+
+Executes a bash script
+
+Typically, this will be called by a script's shebang
+
+### `[ARGS]...`
+
+arguments to pass to script
+
+## Flags
+
+### `-h`
+
+show help
+
+### `--help`
+
+show help
diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
new file mode 100644
index 0000000..5f686d4
--- /dev/null
+++ b/docs/cli/reference/commands.json
@@ -0,0 +1,527 @@
+{
+  "name": "usage-cli",
+  "bin": "usage",
+  "cmd": {
+    "full_cmd": [],
+    "usage": "[--usage-spec] [COMPLETIONS] <SUBCOMMAND>",
+    "subcommands": {
+      "bash": {
+        "full_cmd": ["bash"],
+        "usage": "bash [-h] [--help] <SCRIPT> [ARGS]...",
+        "subcommands": {},
+        "args": [
+          {
+            "name": "SCRIPT",
+            "usage": "<SCRIPT>",
+            "required": true,
+            "hide": false
+          },
+          {
+            "name": "ARGS",
+            "usage": "[ARGS]...",
+            "help": "arguments to pass to script",
+            "help_first_line": "arguments to pass to script",
+            "required": false,
+            "var": true,
+            "hide": false
+          }
+        ],
+        "flags": [
+          {
+            "name": "h",
+            "usage": "-h",
+            "help": "show help",
+            "help_first_line": "show help",
+            "short": ["h"],
+            "long": [],
+            "hide": false,
+            "global": false
+          },
+          {
+            "name": "help",
+            "usage": "--help",
+            "help": "show help",
+            "help_first_line": "show help",
+            "short": [],
+            "long": ["help"],
+            "hide": false,
+            "global": false
+          }
+        ],
+        "mounts": [],
+        "hide": false,
+        "help": "Executes a bash script",
+        "help_long": "Executes a bash script\n\nTypically, this will be called by a script's shebang",
+        "name": "bash",
+        "aliases": [],
+        "hidden_aliases": [],
+        "examples": []
+      },
+      "complete-word": {
+        "full_cmd": ["complete-word"],
+        "usage": "complete-word [FLAGS] [WORDS]...",
+        "subcommands": {},
+        "args": [
+          {
+            "name": "WORDS",
+            "usage": "[WORDS]...",
+            "help": "user's input from the command line",
+            "help_first_line": "user's input from the command line",
+            "required": false,
+            "var": true,
+            "hide": false
+          }
+        ],
+        "flags": [
+          {
+            "name": "shell",
+            "usage": "--shell <SHELL>",
+            "short": [],
+            "long": ["shell"],
+            "hide": false,
+            "global": false,
+            "arg": {
+              "name": "SHELL",
+              "usage": "<SHELL>",
+              "required": true,
+              "hide": false,
+              "choices": {
+                "choices": ["bash", "fish", "zsh"]
+              }
+            }
+          },
+          {
+            "name": "file",
+            "usage": "-f --file <FILE>",
+            "help": "usage spec file or script with usage shebang",
+            "help_first_line": "usage spec file or script with usage shebang",
+            "short": ["f"],
+            "long": ["file"],
+            "hide": false,
+            "global": false,
+            "arg": {
+              "name": "FILE",
+              "usage": "<FILE>",
+              "required": true,
+              "hide": false
+            }
+          },
+          {
+            "name": "spec",
+            "usage": "-s --spec <SPEC>",
+            "help": "raw string spec input",
+            "help_first_line": "raw string spec input",
+            "short": ["s"],
+            "long": ["spec"],
+            "hide": false,
+            "global": false,
+            "arg": {
+              "name": "SPEC",
+              "usage": "<SPEC>",
+              "required": true,
+              "hide": false
+            }
+          },
+          {
+            "name": "cword",
+            "usage": "--cword <CWORD>",
+            "help": "current word index",
+            "help_first_line": "current word index",
+            "short": [],
+            "long": ["cword"],
+            "hide": false,
+            "global": false,
+            "arg": {
+              "name": "CWORD",
+              "usage": "<CWORD>",
+              "required": true,
+              "hide": false
+            }
+          }
+        ],
+        "mounts": [],
+        "hide": false,
+        "name": "complete-word",
+        "aliases": ["cw"],
+        "hidden_aliases": [],
+        "examples": []
+      },
+      "exec": {
+        "full_cmd": ["exec"],
+        "usage": "exec <ARGS>…",
+        "subcommands": {},
+        "args": [
+          {
+            "name": "COMMAND",
+            "usage": "<COMMAND>",
+            "help": "command to execute after parsing usage spec",
+            "help_first_line": "command to execute after parsing usage spec",
+            "required": true,
+            "hide": false
+          },
+          {
+            "name": "BIN",
+            "usage": "<BIN>",
+            "help": "path to script to execute",
+            "help_first_line": "path to script to execute",
+            "required": true,
+            "hide": false
+          },
+          {
+            "name": "ARGS",
+            "usage": "[ARGS]...",
+            "help": "arguments to pass to script",
+            "help_first_line": "arguments to pass to script",
+            "required": false,
+            "var": true,
+            "hide": false
+          }
+        ],
+        "flags": [],
+        "mounts": [],
+        "hide": true,
+        "name": "exec",
+        "aliases": ["x"],
+        "hidden_aliases": [],
+        "examples": []
+      },
+      "generate": {
+        "full_cmd": ["generate"],
+        "usage": "generate <SUBCOMMAND>",
+        "subcommands": {
+          "completion": {
+            "full_cmd": ["generate", "completion"],
+            "usage": "generate completion [FLAGS] <SHELL> <BIN>",
+            "subcommands": {},
+            "args": [
+              {
+                "name": "SHELL",
+                "usage": "<SHELL>",
+                "required": true,
+                "hide": false,
+                "choices": {
+                  "choices": ["bash", "fish", "zsh"]
+                }
+              },
+              {
+                "name": "BIN",
+                "usage": "<BIN>",
+                "help": "The CLI which we're generates completions for",
+                "help_first_line": "The CLI which we're generates completions for",
+                "required": true,
+                "hide": false
+              }
+            ],
+            "flags": [
+              {
+                "name": "cache-key",
+                "usage": "--cache-key <CACHE_KEY>",
+                "help": "A cache key to use for storing the results of calling the CLI with --usage-cmd",
+                "help_first_line": "A cache key to use for storing the results of calling the CLI with --usage-cmd",
+                "short": [],
+                "long": ["cache-key"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "CACHE_KEY",
+                  "usage": "<CACHE_KEY>",
+                  "required": true,
+                  "hide": false
+                }
+              },
+              {
+                "name": "file",
+                "usage": "-f --file <FILE>",
+                "help": "A .usage.kdl spec file to use for generating completions",
+                "help_first_line": "A .usage.kdl spec file to use for generating completions",
+                "short": ["f"],
+                "long": ["file"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "FILE",
+                  "usage": "<FILE>",
+                  "required": true,
+                  "hide": false
+                }
+              },
+              {
+                "name": "usage-cmd",
+                "usage": "--usage-cmd <USAGE_CMD>",
+                "help": "A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"",
+                "help_first_line": "A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"",
+                "short": [],
+                "long": ["usage-cmd"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "USAGE_CMD",
+                  "usage": "<USAGE_CMD>",
+                  "required": true,
+                  "hide": false
+                }
+              }
+            ],
+            "mounts": [],
+            "hide": false,
+            "name": "completion",
+            "aliases": ["c"],
+            "hidden_aliases": ["complete", "completions"],
+            "examples": []
+          },
+          "fig": {
+            "full_cmd": ["generate", "fig"],
+            "usage": "generate fig [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,
+                  "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,
+                  "hide": false
+                }
+              },
+              {
+                "name": "out-file",
+                "usage": "--out-file <OUT_FILE>",
+                "help": "File on where to save the generated Fig spec",
+                "help_first_line": "File on where to save the generated Fig spec",
+                "short": [],
+                "long": ["out-file"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "OUT_FILE",
+                  "usage": "<OUT_FILE>",
+                  "required": true,
+                  "hide": false
+                }
+              }
+            ],
+            "mounts": [],
+            "hide": false,
+            "name": "fig",
+            "aliases": [],
+            "hidden_aliases": [],
+            "examples": []
+          },
+          "json": {
+            "full_cmd": ["generate", "json"],
+            "usage": "generate json [-f --file <FILE>] [--spec <SPEC>]",
+            "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,
+                  "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,
+                  "hide": false
+                }
+              }
+            ],
+            "mounts": [],
+            "hide": false,
+            "help": "Outputs a usage spec in json format",
+            "name": "json",
+            "aliases": [],
+            "hidden_aliases": [],
+            "examples": []
+          },
+          "markdown": {
+            "full_cmd": ["generate", "markdown"],
+            "usage": "generate markdown <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"],
+                "required": true,
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "FILE",
+                  "usage": "<FILE>",
+                  "required": true,
+                  "hide": false
+                }
+              },
+              {
+                "name": "multi",
+                "usage": "-m --multi",
+                "help": "Render each subcommand as a separate markdown file",
+                "help_first_line": "Render each subcommand as a separate markdown file",
+                "short": ["m"],
+                "long": ["multi"],
+                "hide": false,
+                "global": false
+              },
+              {
+                "name": "url-prefix",
+                "usage": "--url-prefix <URL_PREFIX>",
+                "help": "Prefix to add to all URLs",
+                "help_first_line": "Prefix to add to all URLs",
+                "short": [],
+                "long": ["url-prefix"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "URL_PREFIX",
+                  "usage": "<URL_PREFIX>",
+                  "required": true,
+                  "hide": false
+                }
+              },
+              {
+                "name": "html-encode",
+                "usage": "--html-encode",
+                "help": "Escape HTML in markdown",
+                "help_first_line": "Escape HTML in markdown",
+                "short": [],
+                "long": ["html-encode"],
+                "hide": false,
+                "global": false
+              },
+              {
+                "name": "out-dir",
+                "usage": "--out-dir <OUT_DIR>",
+                "help": "Output markdown files to this directory",
+                "help_first_line": "Output markdown files to this directory",
+                "short": [],
+                "long": ["out-dir"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "OUT_DIR",
+                  "usage": "<OUT_DIR>",
+                  "required": true,
+                  "hide": false
+                }
+              },
+              {
+                "name": "out-file",
+                "usage": "--out-file <OUT_FILE>",
+                "short": [],
+                "long": ["out-file"],
+                "hide": false,
+                "global": false,
+                "arg": {
+                  "name": "OUT_FILE",
+                  "usage": "<OUT_FILE>",
+                  "required": true,
+                  "hide": false
+                }
+              }
+            ],
+            "mounts": [],
+            "hide": false,
+            "name": "markdown",
+            "aliases": ["md"],
+            "hidden_aliases": [],
+            "examples": []
+          }
+        },
+        "args": [],
+        "flags": [],
+        "mounts": [],
+        "hide": false,
+        "subcommand_required": true,
+        "name": "generate",
+        "aliases": ["g"],
+        "hidden_aliases": [],
+        "examples": []
+      }
+    },
+    "args": [
+      {
+        "name": "COMPLETIONS",
+        "usage": "[COMPLETIONS]",
+        "help": "Outputs completions for the specified shell for completing the `usage` CLI itself",
+        "help_first_line": "Outputs completions for the specified shell for completing the `usage` CLI itself",
+        "required": false,
+        "hide": false
+      }
+    ],
+    "flags": [
+      {
+        "name": "usage-spec",
+        "usage": "--usage-spec",
+        "help": "Outputs a `usage.kdl` spec for this CLI itself",
+        "help_first_line": "Outputs a `usage.kdl` spec for this CLI itself",
+        "short": [],
+        "long": ["usage-spec"],
+        "hide": false,
+        "global": false
+      }
+    ],
+    "mounts": [],
+    "hide": false,
+    "name": "usage",
+    "aliases": [],
+    "hidden_aliases": [],
+    "examples": []
+  },
+  "config": {
+    "props": {}
+  },
+  "version": "1.3.5",
+  "usage": "Usage: usage-cli [OPTIONS] [COMPLETIONS] <COMMAND>",
+  "complete": {},
+  "source_code_link_template": "https://github.com/jdx/usage/blob/main/cli/src/cli/{{path}}.rs",
+  "about": "CLI for working with usage-based CLIs"
+}
diff --git a/docs/cli/reference/complete-word.md b/docs/cli/reference/complete-word.md
new file mode 100644
index 0000000..1fd50ce
--- /dev/null
+++ b/docs/cli/reference/complete-word.md
@@ -0,0 +1,33 @@
+# `usage complete-word`
+
+- **Usage**: `usage complete-word [FLAGS] [WORDS]...`
+- **Aliases**: `cw`
+- **Source code**: [`cli/src/cli/complete-word.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/complete-word.rs)
+
+## Arguments
+
+### `[WORDS]...`
+
+user's input from the command line
+
+## Flags
+
+### `--shell <SHELL>`
+
+**Choices:**
+
+- `bash`
+- `fish`
+- `zsh`
+
+### `-f --file <FILE>`
+
+usage spec file or script with usage shebang
+
+### `-s --spec <SPEC>`
+
+raw string spec input
+
+### `--cword <CWORD>`
+
+current word index
diff --git a/docs/cli/reference/generate.md b/docs/cli/reference/generate.md
new file mode 100644
index 0000000..1f0f577
--- /dev/null
+++ b/docs/cli/reference/generate.md
@@ -0,0 +1,12 @@
+# `usage generate`
+
+- **Usage**: `usage generate <SUBCOMMAND>`
+- **Aliases**: `g`
+- **Source code**: [`cli/src/cli/generate.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate.rs)
+
+## Subcommands
+
+- [`usage generate completion [FLAGS] <SHELL> <BIN>`](/cli/reference//generate/completion.md)
+- [`usage generate fig [FLAGS]`](/cli/reference//generate/fig.md)
+- [`usage generate json [-f --file <FILE>] [--spec <SPEC>]`](/cli/reference//generate/json.md)
+- [`usage generate markdown <FLAGS>`](/cli/reference//generate/markdown.md)
diff --git a/docs/cli/reference/generate/completion.md b/docs/cli/reference/generate/completion.md
new file mode 100644
index 0000000..7a33c1b
--- /dev/null
+++ b/docs/cli/reference/generate/completion.md
@@ -0,0 +1,33 @@
+# `usage generate completion`
+
+- **Usage**: `usage generate completion [FLAGS] <SHELL> <BIN>`
+- **Aliases**: `c`
+- **Source code**: [`cli/src/cli/generate/completion.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/completion.rs)
+
+## Arguments
+
+### `<SHELL>`
+
+**Choices:**
+
+- `bash`
+- `fish`
+- `zsh`
+
+### `<BIN>`
+
+The CLI which we're generates completions for
+
+## Flags
+
+### `--cache-key <CACHE_KEY>`
+
+A cache key to use for storing the results of calling the CLI with --usage-cmd
+
+### `-f --file <FILE>`
+
+A .usage.kdl spec file to use for generating completions
+
+### `--usage-cmd <USAGE_CMD>`
+
+A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to "$bin --usage"
diff --git a/docs/cli/reference/generate/fig.md b/docs/cli/reference/generate/fig.md
new file mode 100644
index 0000000..b2dbbb3
--- /dev/null
+++ b/docs/cli/reference/generate/fig.md
@@ -0,0 +1,18 @@
+# `usage generate fig`
+
+- **Usage**: `usage generate fig [FLAGS]`
+- **Source code**: [`cli/src/cli/generate/fig.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/fig.rs)
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `--spec <SPEC>`
+
+raw string spec input
+
+### `--out-file <OUT_FILE>`
+
+File on where to save the generated Fig spec
diff --git a/docs/cli/reference/generate/json.md b/docs/cli/reference/generate/json.md
new file mode 100644
index 0000000..fa8bd19
--- /dev/null
+++ b/docs/cli/reference/generate/json.md
@@ -0,0 +1,16 @@
+# `usage generate json`
+
+- **Usage**: `usage generate json [-f --file <FILE>] [--spec <SPEC>]`
+- **Source code**: [`cli/src/cli/generate/json.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/json.rs)
+
+Outputs a usage spec in json format
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `--spec <SPEC>`
+
+raw string spec input
diff --git a/docs/cli/reference/generate/markdown.md b/docs/cli/reference/generate/markdown.md
new file mode 100644
index 0000000..364e8c3
--- /dev/null
+++ b/docs/cli/reference/generate/markdown.md
@@ -0,0 +1,29 @@
+# `usage generate markdown`
+
+- **Usage**: `usage generate markdown <FLAGS>`
+- **Aliases**: `md`
+- **Source code**: [`cli/src/cli/generate/markdown.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/markdown.rs)
+
+## Flags
+
+### `-f --file <FILE>`
+
+A usage spec taken in as a file
+
+### `-m --multi`
+
+Render each subcommand as a separate markdown file
+
+### `--url-prefix <URL_PREFIX>`
+
+Prefix to add to all URLs
+
+### `--html-encode`
+
+Escape HTML in markdown
+
+### `--out-dir <OUT_DIR>`
+
+Output markdown files to this directory
+
+### `--out-file <OUT_FILE>`
diff --git a/docs/cli/reference/index.md b/docs/cli/reference/index.md
new file mode 100644
index 0000000..cc396f5
--- /dev/null
+++ b/docs/cli/reference/index.md
@@ -0,0 +1,29 @@
+# `usage`
+
+**Usage**: `usage [--usage-spec] [COMPLETIONS] <SUBCOMMAND>`
+
+**Version**: 1.3.5
+
+- **Usage**: `usage [--usage-spec] [COMPLETIONS] <SUBCOMMAND>`
+
+## Arguments
+
+### `[COMPLETIONS]`
+
+Outputs completions for the specified shell for completing the `usage` CLI itself
+
+## Flags
+
+### `--usage-spec`
+
+Outputs a `usage.kdl` spec for this CLI itself
+
+## Subcommands
+
+- [`usage bash [-h] [--help] <SCRIPT> [ARGS]...`](/cli/reference//bash.md)
+- [`usage complete-word [FLAGS] [WORDS]...`](/cli/reference//complete-word.md)
+- [`usage generate <SUBCOMMAND>`](/cli/reference//generate.md)
+- [`usage generate completion [FLAGS] <SHELL> <BIN>`](/cli/reference//generate/completion.md)
+- [`usage generate fig [FLAGS]`](/cli/reference//generate/fig.md)
+- [`usage generate json [-f --file <FILE>] [--spec <SPEC>]`](/cli/reference//generate/json.md)
+- [`usage generate markdown <FLAGS>`](/cli/reference//generate/markdown.md)
diff --git a/examples/docs/MISE_INLINE.md b/examples/docs/MISE_INLINE.md
index 28b679f..f6ec0c3 100644
--- a/examples/docs/MISE_INLINE.md
+++ b/examples/docs/MISE_INLINE.md
@@ -433,6 +433,8 @@ If not provided, the nearest mise.toml file will be used
 
 #### `-t --type <TYPE>`
 
+Display the value of a setting in a mise.toml file
+
 **Choices:**
 
 - `string`
@@ -736,6 +738,8 @@ root directory to search for tasks
 
 #### `-s --style <STYLE>`
 
+[experimental] Generate documentation for tasks in a project
+
 **Choices:**
 
 - `simple`
diff --git a/examples/docs/MISE_MULTI.md b/examples/docs/MISE_MULTI.md
index 28b679f..f6ec0c3 100644
--- a/examples/docs/MISE_MULTI.md
+++ b/examples/docs/MISE_MULTI.md
@@ -433,6 +433,8 @@ If not provided, the nearest mise.toml file will be used
 
 #### `-t --type <TYPE>`
 
+Display the value of a setting in a mise.toml file
+
 **Choices:**
 
 - `string`
@@ -736,6 +738,8 @@ root directory to search for tasks
 
 #### `-s --style <STYLE>`
 
+[experimental] Generate documentation for tasks in a project
+
 **Choices:**
 
 - `simple`
diff --git a/lib/src/docs/markdown/templates/arg_template.md.tera b/lib/src/docs/markdown/templates/arg_template.md.tera
index fb0d646..08d94a4 100644
--- a/lib/src/docs/markdown/templates/arg_template.md.tera
+++ b/lib/src/docs/markdown/templates/arg_template.md.tera
@@ -1,4 +1,4 @@
-{%- if arg.help_long_md %}{% set help = arg.long_help %}{% elif arg.help_long %}{% set help = arg.help_long %}{% else %}{% set help = arg.help %}{% endif %}
+{%- if arg.help_long_md %}{% set help = arg.long_help %}{% elif arg.help_long %}{% set help = arg.help_long %}{% elif arg.help %}{% set help = arg.help %}{% endif %}
 
 {%- if help %}
 
diff --git a/lib/src/docs/markdown/templates/cmd_template.md.tera b/lib/src/docs/markdown/templates/cmd_template.md.tera
index 9e803a6..1fdbd91 100644
--- a/lib/src/docs/markdown/templates/cmd_template.md.tera
+++ b/lib/src/docs/markdown/templates/cmd_template.md.tera
@@ -1,7 +1,7 @@
 {%- set source_code_link = source_code_link(spec=spec, cmd=cmd) %}
-{%- if cmd.before_help_md %}{% set before_help = cmd.before_help_md %}{% elif cmd.before_help_long %}{% set before_help = cmd.before_help_long %}{% else %}{% set before_help = cmd.before_help %}{% endif %}
-{%- if cmd.help_md %}{% set help = cmd.help_md %}{% elif cmd.help_long %}{% set help = cmd.help_long %}{% else %}{% set help = cmd.help %}{% endif %}
-{%- if cmd.after_help_md %}{% set after_help = cmd.after_help_md %}{% elif cmd.after_help_long %}{% set after_help = cmd.after_help_long %}{% else %}{% set after_help = cmd.after_help %}{% endif %}
+{%- if cmd.before_help_md %}{% set before_help = cmd.before_help_md %}{% elif cmd.before_help_long %}{% set before_help = cmd.before_help_long %}{% elif cmd.before_help %}{% set before_help = cmd.before_help %}{% endif %}
+{%- if cmd.help_md %}{% set help = cmd.help_md %}{% elif cmd.help_long %}{% set help = cmd.help_long %}{% elif cmd.help %}{% set help = cmd.help %}{% else %}{% set help = "" %}{% endif %}
+{%- if cmd.after_help_md %}{% set after_help = cmd.after_help_md %}{% elif cmd.after_help_long %}{% set after_help = cmd.after_help_long %}{% elif cmd.after_help %}{% set after_help = cmd.after_help %}{% endif %}
 {%- set full_cmd = cmd.full_cmd | join(sep=" ") %}
 {%- if multi -%}
 {{- "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ full_cmd | trim }}`
@@ -64,7 +64,7 @@
 
 {%- if multi %}
 {%- for name, cmd in cmd.subcommands %}
-{%- if cmd.hide == false %}
+{%- if not cmd.hide or cmd.hide == false %}
 {%- if loop.first %}
 
 {{ "#" | repeat(count=header_level) }}# Subcommands
diff --git a/lib/src/docs/markdown/templates/flag_template.md.tera b/lib/src/docs/markdown/templates/flag_template.md.tera
index 673732f..6e45420 100644
--- a/lib/src/docs/markdown/templates/flag_template.md.tera
+++ b/lib/src/docs/markdown/templates/flag_template.md.tera
@@ -1,4 +1,4 @@
-{%- if flag.help_long_md %}{% set help = flag.long_help %}{% elif flag.help_long %}{% set help = flag.help_long %}{% else %}{% set help = flag.help %}{% endif %}
+{%- if flag.help_long_md %}{% set help = flag.long_help %}{% elif flag.help_long %}{% set help = flag.help_long %}{% elif flag.help %}{% set help = flag.help %}{% endif %}
 {%- if help %}
 
 {{ help | escape_md }}
diff --git a/lib/src/docs/markdown/templates/spec_template.md.tera b/lib/src/docs/markdown/templates/spec_template.md.tera
index 6f1cae6..d8b9e8b 100644
--- a/lib/src/docs/markdown/templates/spec_template.md.tera
+++ b/lib/src/docs/markdown/templates/spec_template.md.tera
@@ -1,4 +1,4 @@
-{%- set about = spec.about_long | default(value=spec.about) %}
+{%- set about = spec.about_long | default(value=spec.about | default(value="")) %}
 {%- set cmd = spec.cmd %}
 {%- set full_cmd = cmd.full_cmd | join(sep=" ") %}
 {{- "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ full_cmd | trim }}`
diff --git a/lib/src/spec/arg.rs b/lib/src/spec/arg.rs
index e300c78..d23c450 100644
--- a/lib/src/spec/arg.rs
+++ b/lib/src/spec/arg.rs
@@ -9,22 +9,32 @@ use std::str::FromStr;
 use crate::error::UsageErr;
 use crate::spec::context::ParsingContext;
 use crate::spec::helpers::NodeHelper;
+use crate::spec::is_false;
 use crate::{string, SpecChoices};
 
 #[derive(Debug, Default, Clone, Serialize)]
 pub struct SpecArg {
     pub name: String,
     pub usage: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help_long: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help_md: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help_first_line: Option<String>,
     pub required: bool,
+    #[serde(skip_serializing_if = "is_false")]
     pub var: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub var_min: Option<usize>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub var_max: Option<usize>,
     pub hide: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub default: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub choices: Option<SpecChoices>,
 }
 
diff --git a/lib/src/spec/cmd.rs b/lib/src/spec/cmd.rs
index 0bbb927..c6918ba 100644
--- a/lib/src/spec/cmd.rs
+++ b/lib/src/spec/cmd.rs
@@ -5,6 +5,7 @@ use crate::error::UsageErr;
 use crate::sh::sh;
 use crate::spec::context::ParsingContext;
 use crate::spec::helpers::NodeHelper;
+use crate::spec::is_false;
 use crate::spec::mount::SpecMount;
 use crate::{Spec, SpecArg, SpecFlag};
 use indexmap::IndexMap;
@@ -20,20 +21,31 @@ pub struct SpecCommand {
     pub args: Vec<SpecArg>,
     pub flags: Vec<SpecFlag>,
     pub mounts: Vec<SpecMount>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub deprecated: Option<String>,
     pub hide: bool,
+    #[serde(skip_serializing_if = "is_false")]
     pub subcommand_required: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help_long: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help_md: Option<String>,
     pub name: String,
     pub aliases: Vec<String>,
     pub hidden_aliases: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub before_help: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub before_help_long: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub before_help_md: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub after_help: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub after_help_long: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub after_help_md: Option<String>,
     pub examples: Vec<SpecExample>,
 
diff --git a/lib/src/spec/complete.rs b/lib/src/spec/complete.rs
index 8dfabc6..618ab5d 100644
--- a/lib/src/spec/complete.rs
+++ b/lib/src/spec/complete.rs
@@ -7,7 +7,9 @@ use crate::spec::helpers::NodeHelper;
 #[derive(Debug, Default, Clone, Serialize, Deserialize)]
 pub struct SpecComplete {
     pub name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub run: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub type_: Option<String>,
 }
 
diff --git a/lib/src/spec/flag.rs b/lib/src/spec/flag.rs
index b935ba4..6bad601 100644
--- a/lib/src/spec/flag.rs
+++ b/lib/src/spec/flag.rs
@@ -9,26 +9,38 @@ use crate::error::UsageErr::InvalidFlag;
 use crate::error::{Result, UsageErr};
 use crate::spec::context::ParsingContext;
 use crate::spec::helpers::NodeHelper;
+use crate::spec::is_false;
 use crate::{string, SpecArg, SpecChoices};
 
 #[derive(Debug, Default, Clone, Serialize)]
 pub struct SpecFlag {
     pub name: String,
     pub usage: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help_long: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help_md: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub help_first_line: Option<String>,
     pub short: Vec<char>,
     pub long: Vec<String>,
+    #[serde(skip_serializing_if = "is_false")]
     pub required: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub deprecated: Option<String>,
+    #[serde(skip_serializing_if = "is_false")]
     pub var: bool,
     pub hide: bool,
     pub global: bool,
+    #[serde(skip_serializing_if = "is_false")]
     pub count: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub arg: Option<SpecArg>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub default: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub negate: Option<String>,
 }
 
diff --git a/lib/src/spec/mod.rs b/lib/src/spec/mod.rs
index f29a223..a1dbe9a 100644
--- a/lib/src/spec/mod.rs
+++ b/lib/src/spec/mod.rs
@@ -32,16 +32,24 @@ pub struct Spec {
     pub bin: String,
     pub cmd: SpecCommand,
     pub config: SpecConfig,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub version: Option<String>,
     pub usage: String,
     pub complete: IndexMap<String, SpecComplete>,
 
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub source_code_link_template: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub author: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub about: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub about_long: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub about_md: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub disable_help: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub min_usage_version: Option<String>,
 }
 
@@ -368,6 +376,16 @@ impl From<&clap::Command> for Spec {
     }
 }
 
+#[inline]
+pub fn is_true(b: &bool) -> bool {
+    *b
+}
+
+#[inline]
+pub fn is_false(b: &bool) -> bool {
+    !is_true(b)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/mise.toml b/mise.toml
index a77126f..5acfbc6 100644
--- a/mise.toml
+++ b/mise.toml
@@ -44,6 +44,7 @@ run = 'usage g completion fish -f examples/example.sh > ~/.config/fish/completio
 raw = true
 
 [tasks."docs:dev"]
+alias = "docs"
 dir = 'docs'
 run = 'npm run docs:dev'
 
@@ -84,7 +85,9 @@ depends = ['render:*']
 depends = ['build']
 run = [
     'usage --usage-spec > cli/usage.usage.kdl',
-    'usage g md -f cli/usage.usage.kdl --out-file docs/cli/reference.md',
+    'rm -rf docs/cli/reference && mkdir -p docs/cli/reference',
+    'usage g json -f cli/usage.usage.kdl > docs/cli/reference/commands.json',
+    'usage g md -mf cli/usage.usage.kdl --out-dir docs/cli/reference --url-prefix /cli/reference/',
     'usage g completion bash usage --usage-cmd "usage --usage-spec" > cli/assets/completions/usage.bash',
     'usage g completion fish usage --usage-cmd "usage --usage-spec" > cli/assets/completions/usage.fish',
     'usage g completion zsh  usage --usage-cmd "usage --usage-spec" > cli/assets/completions/_usage',