getting-started.md

Getting Started

Installation

politty requires Zod v4.

npm install politty zod
# or
pnpm add politty zod
# or
yarn add politty zod

Your First Command

Here's a minimal "Hello World" example.

import { defineCommand, runMain } from "politty";

const command = defineCommand({
  name: "my-cli",
  run: () => {
    console.log("Hello, World!");
  },
});

runMain(command);

You can run it locally with tsx or ts-node:

$ npx tsx index.ts
Hello, World!

Adding Arguments

Use z.object and arg() to define arguments.

import { z } from "zod";
import { defineCommand, runMain, arg } from "politty";

const command = defineCommand({
  name: "greet",
  args: z.object({
    // Positional argument: greet <name>
    name: arg(z.string(), {
      positional: true,
      description: "Name to greet",
    }),

    // Option flag: --loud / -l
    loud: arg(z.boolean().default(false), {
      alias: "l",
      description: "Greet loudly",
    }),
  }),
  run: (args) => {
    const message = `Hello, ${args.name}!`;
    console.log(args.loud ? message.toUpperCase() : message);
  },
});

runMain(command);

$ npx tsx greet.ts World
Hello, World!

$ npx tsx greet.ts World --loud
HELLO, WORLD!

Next Steps

Now that you understand the basics, check out these guides for more details:

• Essentials: Details on arguments, validation, and lifecycle hooks
• Advanced Features: Subcommands, nested structures, complex schemas
• Recipes: Testing techniques, error handling, configuration, and faster startup with the compile cache (politty generate-shim)