{"id":30773464,"url":"https://github.com/timmikeladze/zod-command","last_synced_at":"2026-01-20T16:37:11.788Z","repository":{"id":295470552,"uuid":"953282007","full_name":"TimMikeladze/zod-command","owner":"TimMikeladze","description":"A Zod-powered CLI framework for building command-line tools in TypeScript.","archived":false,"fork":false,"pushed_at":"2025-08-01T01:58:59.000Z","size":256,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-28T11:22:05.537Z","etag":null,"topics":["cli","cli-framework","typescript-cli","zod","zod-cli","zod-command"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/TimMikeladze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2025-03-23T01:32:15.000Z","updated_at":"2025-06-10T03:59:58.000Z","dependencies_parsed_at":"2025-05-25T18:57:34.252Z","dependency_job_id":"82d23238-475e-4809-8e00-90d79deaf627","html_url":"https://github.com/TimMikeladze/zod-command","commit_stats":null,"previous_names":["timmikeladze/mydevtool","timmikeladze/zod-command"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/TimMikeladze/zod-command","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Fzod-command","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Fzod-command/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Fzod-command/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Fzod-command/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimMikeladze","download_url":"https://codeload.github.com/TimMikeladze/zod-command/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimMikeladze%2Fzod-command/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273699712,"owners_count":25152285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cli","cli-framework","typescript-cli","zod","zod-cli","zod-command"],"created_at":"2025-09-05T01:52:11.129Z","updated_at":"2025-10-26T11:35:27.716Z","avatar_url":"https://github.com/TimMikeladze.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZodCommand\n\nA Zod-powered CLI framework for building command-line tools in TypeScript.\n\n## Features\n\n- **Type-safe commands** with input/output validation using Zod schemas\n- **Command hierarchy** with subcommands and grouping\n- **Middleware system** for cross-cutting concerns\n- **Plugin architecture** for extensibility\n- **Configuration management** with multiple file formats (JSON, YAML, JS, TS)\n- **Environment variable support** with automatic type conversion\n- **Comprehensive logging** with different levels\n- **Command aliases** for better UX\n- **Built-in help system** with automatic documentation generation\n\n## Installation\n\n```bash\nnpm install zod-command\n# or\nyarn add zod-command\n# or\npnpm add zod-command\n```\n\n## Quick Start\n\n### Basic CLI Setup\n\n```typescript\nimport ZodCommand, { z } from 'zod-command';\n\nconst cli = new ZodCommand({\n  name: \"my-cli\",\n  version: \"1.0.0\", \n  description: \"My awesome CLI tool\",\n  aliases: [\"zod-command\", \"zc\"]\n});\n\n// Add a simple command\ncli.add({\n  command: \"greet\",\n  description: \"Greet someone\"\n})\n.input(z.object({\n  name: z.string().describe(\"Name of the person to greet\"),\n  uppercase: z.boolean().optional().describe(\"Convert to uppercase\")\n}))\n.action(async ({ parsedInput }) =\u003e {\n  const greeting = `Hello, ${parsedInput.name}!`;\n  return {\n    message: parsedInput.uppercase ? greeting.toUpperCase() : greeting\n  };\n});\n\n// Run the CLI\ncli.run();\n```\n\n### Advanced Example with Subcommands\n\n```typescript\nimport ZodCommand, { z } from 'zod-command';\n\nconst cli = new ZodCommand({\n  name: \"devtool\",\n  version: \"2.0.0\",\n  description: \"A development toolkit\"\n});\n\n// Parent command with subcommands\nconst userCmd = cli.add({\n  command: \"user\",\n  description: \"User management commands\",\n  group: \"Management\"\n});\n\n// Add subcommand\nuserCmd.sub(\"create\")\n  .input(z.object({\n    email: z.string().email(),\n    name: z.string(),\n    admin: z.boolean().default(false)\n  }))\n  .action(async ({ parsedInput, context }) =\u003e {\n    context.logger.info(`Creating user: ${parsedInput.name}`);\n    // User creation logic here\n    return { userId: \"123\", created: true };\n  });\n\n// Another subcommand\nuserCmd.sub(\"delete\")\n  .input(z.object({\n    userId: z.string(),\n    force: z.boolean().default(false)\n  }))\n  .action(async ({ parsedInput, context }) =\u003e {\n    if (!parsedInput.force) {\n      context.logger.warn(\"Use --force to confirm deletion\");\n      return { deleted: false };\n    }\n    // Deletion logic here\n    return { deleted: true };\n  });\n\ncli.run();\n```\n\n## Configuration Management\n\nZodCommand supports multiple configuration file formats and environment variables:\n\n```typescript\nimport ZodCommand, { z } from 'zod-command';\n\nconst configSchema = z.object({\n  database: z.object({\n    host: z.string().default(\"localhost\"),\n    port: z.number().default(5432),\n    name: z.string()\n  }),\n  debug: z.boolean().default(false)\n});\n\nconst cli = new ZodCommand({\n  name: \"my-app\"\n});\n\ncli.configure({\n  schema: configSchema,\n  configFiles: [\n    \"./config.json\",\n    \"./config.yaml\", \n    \"./config.js\",\n    \"./config.ts\"\n  ],\n  envPrefix: \"MYAPP_\",\n  defaults: {\n    database: {\n      host: \"localhost\",\n      port: 5432\n    }\n  }\n});\n\ncli.add({\n  command: \"connect\",\n  description: \"Connect to database\"\n})\n.input(z.object({}))\n.action(async ({ config, context }) =\u003e {\n  const dbConfig = config as z.infer\u003ctypeof configSchema\u003e;\n  context.logger.info(`Connecting to ${dbConfig.database.host}:${dbConfig.database.port}`);\n  // Connection logic here\n});\n\ncli.run();\n```\n\n## Middleware System\n\nAdd cross-cutting functionality with middleware:\n\n```typescript\nimport ZodCommand, { z, createMiddleware } from 'zod-command';\n\nconst cli = new ZodCommand({ name: \"my-cli\" });\n\n// Create authentication middleware\nconst authMiddleware = createMiddleware().define(async ({ parsedInput, ctx, next }) =\u003e {\n  // Check authentication\n  const isAuthenticated = checkAuth(); // Your auth logic\n  \n  if (!isAuthenticated) {\n    throw new Error(\"Authentication required\");\n  }\n\n  // Add user info to context\n  const result = await next({ \n    ctx: { \n      ...ctx, \n      user: { id: \"123\", name: \"John\" } \n    } \n  });\n  \n  return result;\n});\n\n// Apply middleware globally\ncli.use(authMiddleware);\n\n// Or apply to specific commands\ncli.add({\n  command: \"protected\",\n  description: \"A protected command\"\n})\n.use(authMiddleware)\n.input(z.object({}))\n.action(async ({ context }) =\u003e {\n  // Access user from context\n  const user = context.user;\n  return { message: `Hello ${user.name}` };\n});\n\ncli.run();\n```\n\n## Plugin System\n\nExtend functionality with plugins:\n\n```typescript\n// plugin.ts\nimport { Plugin, CliBuilder } from 'zod-command';\n\nconst myPlugin: Plugin = {\n  name: \"my-plugin\",\n  version: \"1.0.0\",\n  description: \"My awesome plugin\",\n  initialize: (cli: CliBuilder) =\u003e {\n    cli.add({\n      command: \"plugin-command\",\n      description: \"Command added by plugin\"\n    })\n    .input(z.object({}))\n    .action(async () =\u003e {\n      return { message: \"Hello from plugin!\" };\n    });\n  }\n};\n\nexport default myPlugin;\n```\n\n```json\n// zod-command-plugin.json\n{\n  \"name\": \"my-plugin\",\n  \"version\": \"1.0.0\", \n  \"description\": \"My awesome plugin\",\n  \"main\": \"plugin.js\",\n  \"type\": \"javascript\"\n}\n```\n\nLoad plugins:\n\n```typescript\nconst cli = new ZodCommand({ name: \"my-cli\" });\n\ncli.run({\n  pluginsDir: \"./plugins\"\n});\n```\n\n## Command Examples and Aliases\n\n```typescript\ncli.add({\n  command: \"deploy\",\n  description: \"Deploy application\"\n})\n.input(z.object({\n  environment: z.enum([\"dev\", \"staging\", \"prod\"]),\n  force: z.boolean().default(false)\n}))\n.aliases([\"d\", \"ship\"])\n.examples([\n  { environment: \"dev\" },\n  { environment: \"prod\", force: true }\n])\n.action(async ({ parsedInput }) =\u003e {\n  // Deploy logic\n  return { deployed: true, environment: parsedInput.environment };\n});\n```\n\n## Built-in Commands\n\nZodCommand automatically provides:\n\n- `help` - Display help information\n- `version` - Show version information\n- `help \u003ccommand\u003e` - Show help for specific command\n\n## CLI Usage\n\n```bash\n# Basic usage\nmy-cli greet --name \"World\"\n\n# Subcommands  \nmy-cli user create --email \"user@example.com\" --name \"John Doe\"\n\n# Using aliases\nmy-cli d --environment prod --force\n\n# Get help\nmy-cli help\nmy-cli help user\nmy-cli help user create\n\n# Version info\nmy-cli version\n```\n\n## Environment Variables\n\nConfiguration can be loaded from environment variables:\n\n```bash\n# With envPrefix: \"MYAPP_\"\nexport MYAPP_DATABASE_HOST=localhost\nexport MYAPP_DATABASE_PORT=5432\nexport MYAPP_DEBUG=true\n```\n\n## TypeScript Support\n\nZodCommand is built with TypeScript and provides full type safety:\n\n```typescript\nimport ZodCommand, { z, CommandHandler } from 'zod-command';\n\n// Type-safe input/output schemas\nconst inputSchema = z.object({\n  count: z.number().min(1),\n  format: z.enum([\"json\", \"table\"])\n});\n\nconst outputSchema = z.object({\n  results: z.array(z.string()),\n  total: z.number()\n});\n\n// Type-safe handler\nconst handler: CommandHandler\u003c\n  z.infer\u003ctypeof inputSchema\u003e,\n  z.infer\u003ctypeof outputSchema\u003e\n\u003e = async ({ parsedInput }) =\u003e {\n  return {\n    results: Array(parsedInput.count).fill(\"item\"),\n    total: parsedInput.count\n  };\n};\n\ncli.add({\n  command: \"generate\",\n  description: \"Generate items\"\n})\n.input(inputSchema)\n.output(outputSchema)\n.action(handler);\n```\n\n## API Reference\n\n### ZodCommand Class\n\n- `constructor(metadata?: CliMetadata)` - Create new CLI instance\n- `add(config: CommandConfig)` - Add a command\n- `configure(options: ConfigOptions)` - Set up configuration\n- `run(options?: CliOptions)` - Run the CLI\n- `setMetadata(metadata: CliMetadata)` - Update CLI metadata\n\n### ActionBuilder Class\n\n- `input(schema: ZodType)` - Set input validation schema\n- `output(schema: ZodType)` - Set output validation schema  \n- `action(handler: CommandHandler)` - Set command handler\n- `use(middleware: Middleware)` - Add middleware\n- `sub(name: string)` - Add subcommand\n- `aliases(aliases: string[])` - Set command aliases\n- `examples(examples: any[])` - Add usage examples\n- `meta(metadata: object)` - Set command metadata\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimmikeladze%2Fzod-command","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimmikeladze%2Fzod-command","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimmikeladze%2Fzod-command/lists"}