politty 0.12.5 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +12 -1
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -12,7 +12,7 @@ From simple scripts to complex CLI tools with subcommands, validation, and auto-
12
12
  - **Subcommands**: Build Git-style nested subcommands (with lazy loading and alias support)
13
13
  - **Lifecycle Management**: Guaranteed `setup` → `run` → `cleanup` execution order
14
14
  - **Signal Handling**: Proper SIGINT/SIGTERM handling with guaranteed cleanup execution
15
- - **Auto Help Generation**: Automatically generate help text from definitions
15
+ - **Auto Help Generation**: Automatically generate help text from definitions, plus a `--help-json` flag for structured (JSON) help
16
16
  - **Interactive Prompts**: Prompt for missing arguments with pluggable adapters (clack, inquirer)
17
17
  - **Discriminated Union**: Support for mutually exclusive argument sets
18
18
  - **Skill Management**: Manage agent skills (SKILL.md) with file-based install/uninstall
@@ -149,8 +149,19 @@ Options:
149
149
  -g, --greeting <value> Greeting phrase (default: "Hello")
150
150
  -l, --loud Output in uppercase
151
151
  -h, --help Show help
152
+ -H, --help-all Show help with all subcommand options
153
+ --help-json Show help as JSON
152
154
  ```
153
155
 
156
+ Every command also accepts `--help-json`, which prints the same information as a single JSON object instead of formatted text — useful for tools that consume a CLI's help programmatically (e.g. generating docs or another UI) rather than parsing `--help`'s output:
157
+
158
+ ```bash
159
+ $ my-cli --help-json
160
+ {"name":"greet","commandPath":[],"rootName":"greet","description":"A CLI tool that displays greetings","usage":{"commandName":"greet","hasGlobalOptions":false,"hasOptions":true,"positionals":[{"name":"name","required":true}]},"builtinOptions":{"help":"Show help","helpAll":"Show help with all subcommand options","helpJson":"Show help as JSON"},"schemaType":"object","positionals":[{"name":"name","cliName":"name","positional":true,"required":true,"type":"string","description":"Name of the person to greet"}],"options":[{"name":"greeting","cliName":"greeting","positional":false,"required":false,"type":"string","alias":["g"],"description":"Greeting phrase","defaultValue":"Hello"},{"name":"loud","cliName":"loud","positional":false,"required":false,"type":"boolean","alias":["l"],"description":"Output in uppercase","defaultValue":false}]}
161
+ ```
162
+
163
+ Unlike `--help-all` (which only expands subcommand options when asked), `--help-json` always includes the full recursive subcommand tree — except for legacy subcommands registered without `lazy()`, which have no synchronous metadata available and appear only as `{ name, unresolved: true }`. Call `generateHelpData(command, options?)` directly to get the same `HelpData` object without going through argv parsing — see [API Reference](./docs/api-reference.md#generatehelpdata).
164
+
154
165
  ## Basic Usage
155
166
 
156
167
  ### Defining Arguments
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "politty",
3
- "version": "0.12.5",
3
+ "version": "0.13.0",
4
4
  "description": "A lightweight CLI framework inspired by citty with zod v4 registry integration for type-safe metadata management",
5
5
  "keywords": [
6
6
  "argument-parser",
@@ -67,7 +67,7 @@
67
67
  }
68
68
  },
69
69
  "dependencies": {
70
- "@politty/zod": "^0.2.4"
70
+ "@politty/zod": "^0.3.0"
71
71
  },
72
72
  "devDependencies": {
73
73
  "@types/node": "25.9.5",