{"id":35129504,"url":"https://github.com/kurtgokhan/padrone","last_synced_at":"2026-04-06T11:01:07.029Z","repository":{"id":330773768,"uuid":"1108278365","full_name":"KurtGokhan/padrone","owner":"KurtGokhan","description":"Create type-safe, interactive CLI apps with Zod schemas","archived":false,"fork":false,"pushed_at":"2026-04-01T00:45:53.000Z","size":1544,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T02:42:41.583Z","etag":null,"topics":["ai","argument-parser","cli","command-line","command-line-tool","esm","nodejs","shell","standard-schema","terminal","type-safe","typescript","validation","zod"],"latest_commit_sha":null,"homepage":"http://gkurt.com/padrone/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KurtGokhan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-02T09:03:04.000Z","updated_at":"2026-04-01T00:45:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KurtGokhan/padrone","commit_stats":null,"previous_names":["kurtgokhan/padrone"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/KurtGokhan/padrone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KurtGokhan%2Fpadrone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KurtGokhan%2Fpadrone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KurtGokhan%2Fpadrone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KurtGokhan%2Fpadrone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KurtGokhan","download_url":"https://codeload.github.com/KurtGokhan/padrone/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KurtGokhan%2Fpadrone/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31469743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","argument-parser","cli","command-line","command-line-tool","esm","nodejs","shell","standard-schema","terminal","type-safe","typescript","validation","zod"],"created_at":"2025-12-28T04:56:25.501Z","updated_at":"2026-04-06T11:01:07.021Z","avatar_url":"https://github.com/KurtGokhan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/padrone.svg\" alt=\"Padrone Logo\" width=\"200\" height=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eType-safe CLI framework powered by Zod schemas\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/padrone\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/padrone.svg\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/padrone\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/padrone.svg\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/KurtGokhan/padrone/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/padrone.svg\" alt=\"license\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nDefine your CLI with Zod schemas. Get type safety, validation, help generation, interactive prompts, shell completions, AI tool integration, and more — all from a single source of truth.\n\nBuilt on [Standard Schema](https://github.com/standard-schema/standard-schema), so it also works with Valibot, ArkType, and others.\n\n## Install\n\n```bash\nnpm install padrone zod\n```\n\n## Scaffold a New Project\n\nThe fastest way to get started is with `padrone init`:\n\n```bash\nnpx padrone init my-cli\ncd my-cli \u0026\u0026 bun i \u0026\u0026 bun dev\n```\n\n## Quick Start\n\n```typescript\nimport { createPadrone } from 'padrone';\nimport * as z from 'zod/v4';\n\nconst program = createPadrone('myapp')\n  .command('greet', (c) =\u003e\n    c\n      .arguments(\n        z.object({\n          names: z.array(z.string()).describe('Names to greet'),\n          prefix: z.string().optional().describe('Prefix').meta({ flags: 'p' }),\n        }),\n        { positional: ['...names'] },\n      )\n      .action((args) =\u003e {\n        for (const name of args.names) {\n          console.log(`Hello, ${args.prefix ?? ''} ${name}!`);\n        }\n      }),\n  );\n\nprogram.cli();\n```\n\n```bash\nmyapp greet John Jane -p Mr.\n# Hello, Mr. John!\n# Hello, Mr. Jane!\n```\n\n## What It Does\n\n```typescript\n// Multiple ways to run commands\nprogram.cli();                                              // from process.argv\nprogram.eval('greet John --prefix Mr.');                    // from a string\nprogram.run('greet', { names: ['John'], prefix: 'Mr.' });  // typed args\nprogram.api().greet({ names: ['John'], prefix: 'Mr.' });   // as a function\n\n// Parse without executing\nconst { args } = program.parse('greet John --prefix Mr.');\n\n// Interactive REPL\nfor await (const result of program.repl()) { /* ... */ }\n\n// AI tool for Vercel AI SDK\nconst tool = program.tool();\n\n// MCP server for AI assistants (Claude, Cursor, etc.) [experimental]\nawait program.mcp();  // or: myapp mcp\n\n// REST server with OpenAPI docs [experimental]\nawait program.serve();  // or: myapp serve\n\n// Shell completions\nconst script = program.completion('zsh');\n\n// Help in multiple formats\nprogram.help('greet');                        // text\nprogram.help('greet', { format: 'json' });   // json, markdown, html, ansi\n```\n\n## Features at a Glance\n\n**Arguments** — positional args, variadic args, short flags (`-v`), long aliases (`--dry-run`), auto kebab-case aliases, negatable booleans (`--no-verbose`), custom negation keywords (`--remote` → sets `local` to `false`).\n\n**Env \u0026 Config** — load from environment variables with `.extend(padroneEnv(schema))` and config files with `.extend(padroneConfig({ files, schema }))`. Precedence: CLI \u003e stdin \u003e env \u003e config \u003e defaults.\n\n**Interactive prompts** — auto-prompt for missing fields. Booleans become confirm, enums become select, arrays become multi-select.\n\n**Progress indicators** — auto-managed spinners and progress bars with elapsed time and ETA. `.extend(padroneProgress({ message: 'Deploying...', bar: true, time: true, eta: true }))`.\n\n**Extension-first architecture** — most built-in features (help, version, REPL, color, signal handling, auto-output, stdin, config, interactive, suggestions) are implemented as extensions composed via `.extend()`. Any built-in can be disabled or replaced.\n\n**Interceptors** — middleware hooks for 6 phases (start, parse, validate, execute, error, shutdown). Onion model with `next()`. Extensions register interceptors under the hood. Create your own with `defineInterceptor()`.\n\n**Composition** — mount programs as subcommands with `.mount()`, override commands with merge semantics.\n\n**Wrapping** *(experimental)* — wrap external CLI tools with `.wrap({ command: 'git', args: ['commit'] })`.\n\n## API\n\n### Builder (define commands)\n\n| Method | What it does |\n|--------|-------------|\n| `.arguments(schema, meta?)` | Define args with Zod schema, positional config, field metadata |\n| `.action(handler)` | Set handler `(args, ctx, base?) =\u003e result` |\n| `.command(name, builder)` | Add subcommand (name or `[name, ...aliases]`) |\n| `.context(transform?)` | Define typed context or transform inherited context |\n| `.mount(name, program, options?)` | Mount another program as subcommand tree |\n| `.configure(config)` | Set title, description, version, etc. |\n| `.extend(padroneEnv(schema))` | Map env vars to args (composable extension) |\n| `.extend(padroneConfig({ files, schema }))` | Load args from config files (composable extension) |\n| `.wrap(config)` | Wrap an external CLI tool *(experimental)* |\n| `.extend(padroneProgress(config?))` | Auto-managed progress indicator (extension) |\n| `.intercept(interceptor)` | Register middleware interceptor (use `defineInterceptor()`) |\n| `.extend(extension)` | Apply a build-time extension (bundle of config, commands, interceptors) |\n| `.runtime(runtime)` | Custom I/O (for non-terminal use) |\n| `.updateCheck(config?)` | Background version check |\n| `.async()` | Mark as async validation |\n\n### Program (run commands)\n\n| Method | What it does |\n|--------|-------------|\n| `.cli(prefs?)` | Entry point — parses `process.argv`, throws on errors. Pass `context` in prefs. |\n| `.eval(input, prefs?)` | Parse + validate + execute string, returns errors softly. Pass `context` in prefs. |\n| `.run(command, args, prefs?)` | Run by name with typed args (no validation). Pass `context` in prefs. |\n| `.parse(input?)` | Parse without executing |\n| `.api()` | Generate typed function API |\n| `.repl(options?)` | Interactive REPL session |\n| `.help(command?, prefs?)` | Generate help (text, ansi, markdown, html, json) |\n| `.tool()` | Vercel AI SDK tool definition |\n| `.mcp(prefs?)` | Start MCP server (HTTP or stdio) *(experimental)* |\n| `.serve(prefs?)` | Start REST server with OpenAPI docs *(experimental)* |\n| `.completion(shell?)` | Shell completion script |\n| `.find(command)` | Look up command by path |\n| `.stringify(command?, args?)` | Convert back to CLI string |\n\n### Zod `.meta()` fields\n\n| Field | Example | Purpose |\n|-------|---------|---------|\n| `flags` | `'v'` | Single-char short flag (`-v`) |\n| `alias` | `'dry-run'` | Multi-char long alias (`--dry-run`) |\n| `negative` | `'remote'` | Custom negation keyword for booleans (disables `--no-`) |\n| `examples` | `['8080']` | Example values in help |\n| `deprecated` | `'Use --debug'` | Deprecation warning |\n| `hidden` | `true` | Hide from help |\n| `group` | `'Advanced'` | Group in help output |\n\n### Arguments meta (second param of `.arguments()`)\n\n```typescript\n.arguments(schema, {\n  positional: ['source', '...files', 'dest'],\n  interactive: ['name', 'template'],\n  optionalInteractive: ['typescript'],\n  fields: { verbose: { flags: 'v' } },\n  stdin: 'data',\n  autoAlias: true,  // default\n})\n```\n\n## Agent Skill\n\nGive your AI coding agent knowledge of the Padrone API:\n\n```bash\nnpx skills add KurtGokhan/padrone\n```\n\n## Requirements\n\n- Node.js 18+ or Bun\n- TypeScript 5.0+ (recommended)\n- Zod (or any Standard Schema-compatible library)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkurtgokhan%2Fpadrone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkurtgokhan%2Fpadrone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkurtgokhan%2Fpadrone/lists"}