{"id":30181044,"url":"https://github.com/jaredlunde/zcli","last_synced_at":"2026-03-05T23:42:41.637Z","repository":{"id":65877893,"uuid":"597808227","full_name":"jaredLunde/zcli","owner":"jaredLunde","description":"A framework for building type-safe command-line tools using Zod validators in Deno","archived":false,"fork":false,"pushed_at":"2024-06-20T02:29:16.000Z","size":83,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-11T19:56:16.833Z","etag":null,"topics":["cli","cli-framework","deno","deno-cli","deno-cli-framework","deno-module","zod","zod-cli","zod-lib"],"latest_commit_sha":null,"homepage":"","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/jaredLunde.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2023-02-05T17:46:19.000Z","updated_at":"2025-04-26T19:15:59.000Z","dependencies_parsed_at":"2024-05-11T18:12:40.238Z","dependency_job_id":"09dde439-de14-4e6c-b431-097e93e9d942","html_url":"https://github.com/jaredLunde/zcli","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/jaredLunde/zcli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredLunde%2Fzcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredLunde%2Fzcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredLunde%2Fzcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredLunde%2Fzcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaredLunde","download_url":"https://codeload.github.com/jaredLunde/zcli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredLunde%2Fzcli/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270024697,"owners_count":24514054,"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-08-12T02:00:09.011Z","response_time":80,"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","deno","deno-cli","deno-cli-framework","deno-module","zod","zod-cli","zod-lib"],"created_at":"2025-08-12T08:06:37.056Z","updated_at":"2026-03-05T23:42:36.602Z","avatar_url":"https://github.com/jaredLunde.png","language":"TypeScript","readme":"# zCLI\n\n\u003e A framework for building type-safe command-line tools powered by Zod\n\n## Features\n\n- [x] Zod validations for POSIX-compliant flags and arguments\n- [x] Declarative API\n- [x] S-tier type-safety and autocomplete\n- [x] Built-in `help` command and `--help` flag\n- [x] Built-in `version` command\n- [x] Built-in `completion` command for Bash, Fish, and Zsh\n- [x] Type-safe, persistent configuration\n- [x] Type-safe, persistent key-value cache\n- [x] Type-safe environment variables\n- [x] Built-in internationalization using the user's locale and Deno's `Intl`\n      API\n- [x] Global flags\n- [x] Automated README generation\n- [x] Command and flag aliases\n- [x] `persistentPreRun`, `preRun`, `postRun`, `persistentPostRun` hooks\n\n## Getting started\n\nThe easiest way to get started is to use the\n[`zCLI CLI`](https://github.com/jaredLunde/zcli-cli) to generate a new project.\n\n```sh\n# Install the zCLI CLI\ncurl -fsSL https://raw.githubusercontent.com/jaredLunde/zcli-cli/main/install.sh | sh\n\n# Create a new project\nzcli init my-project\n\n# Add a command\nzcli add my-command\n```\n\n## Example usage\n\n```ts\nimport { args, env, flag, flags, init } from \"https://deno.land/x/zcli/mod.ts\";\nimport { z } from \"https://deno.land/x/zcli/z.ts\";\n\nconst cli = init({\n  globalFlags: flags({\n    verbose: flag({ aliases: [\"v\"] }).oboolean(),\n    raw: flag({ aliases: [\"r\"] }).oboolean(),\n  }),\n\n  ctx: {\n    env: env({\n      DEBUG: env.bool().default(\"false\"),\n    }),\n\n    meta: {\n      version: \"1.3.2\",\n      build: Deno.build,\n      commit: \"development\",\n      date: new Date().toISOString(),\n    },\n  },\n});\n\nconst fetcher = cli\n  .command(\"fetcher\", {\n    args: args({\n      short: \"The URL to fetch\",\n    }).tuple([z.string().url()]),\n\n    flags: flags({\n      method: flag({ short: \"The HTTP method to use\", aliases: [\"m\"] })\n        .enum([\"POST\", \"GET\", \"PUT\", \"PATCH\", \"DELETE\", \"HEAD\"])\n        .default(\"GET\"),\n      headers: flag({ short: \"Add headers to the request\", aliases: [\"H\"] })\n        .array(z.string())\n        .optional(),\n      data: flag({\n        short: \"Send request data\",\n        aliases: [\"d\"],\n      }).ostring(),\n    }),\n  })\n  .describe(\"Fetch a resource from the internet\")\n  .preRun(({ flags, ctx }) =\u003e {\n    if (ctx.env.get(\"DEBUG\")) {\n      console.log(\"Fetching:\", flags.url);\n    }\n  })\n  .run(async ({ flags, ctx }) =\u003e {\n    if (ctx.env.get(\"DEBUG\")) {\n      console.log(\"Fetching:\", flags.url);\n    }\n\n    const response = await fetch(flags.url, {\n      method: flags.method,\n      headers: new Headers(\n        flags.headers?.map((h) =\u003e h.split(\":\").map((s) =\u003e s.trim())),\n      ),\n      body: flags.data,\n    });\n\n    if (flags.json) {\n      console.log(await response.json());\n    } else {\n      console.log(\"Response:\", response);\n    }\n  });\n\nif (import.meta.main) {\n  await fetcher.execute();\n}\n```\n\n## The problem\n\nCommand-line tools written in Node and Deno suffer from a few major issues:\n\n- They are difficult to test\n- They are difficult to type\n- Their boot time is slow\n- Distribution is difficult\n\n## The solution\n\nThis framework aims to solve these issues by providing a declarative, simple API\nfor building type-safe commandline tools using Zod and Deno. It is largely\ninspired by what [tRPC](https://trpc.io) did for RPC APIs, hence the nod to the\nname.\n\nDeno was chosen as the runtime because it is fast, secure, and has a great\nstandard library. It also has a great testing story and is easy to distribute,\nas you can use `deno compile` to create a single binary. In the future, we may\nalso support compiling with `bun` to create a single binary.\n\nInherent boot performance is achieved by limiting the amount of code that is\nbundled into the binary. The flags parser is also about 7x faster than the Deno\nstandard library's parser, though this amounts to a small fraction of the total\nboot/execution time.\n\n```\nbenchmark          time (avg)             (min … max)       p75       p99      p995\n----------------------------------------------------- -----------------------------\nzcli.parse()     1.08 µs/iter   (986.08 ns … 1.37 µs)   1.11 µs   1.37 µs   1.37 µs\nflags.parse()    7.69 µs/iter     (5.22 µs … 6.15 ms)   6.17 µs  19.37 µs  48.85 µs\n\nsummary\n  zcli.parse()\n   7.11x faster than flags.parse()\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredlunde%2Fzcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaredlunde%2Fzcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredlunde%2Fzcli/lists"}