pok

A file-based CLI framework for building beautiful command-line interfaces.

Why pok?

Building CLI tools shouldn't require wrestling with argument parsers, manually wiring up commands, or choosing between type safety and developer experience. pok takes a different approach.

File-Based Routing

Commands are discovered from the filesystem. No registration, no configuration—just create a file:

commands/
  dev.ts           → mycli dev
  deploy.ts        → mycli deploy
  db.migrate.ts    → mycli db migrate

Type-Safe by Default

Define your command's interface with Zod schemas. TypeScript infers everything:

export const command = defineCommand({
  context: {
    env: {
      from: 'flag',
      schema: z.enum(['dev', 'staging', 'prod']),
    },
  },
  run: async (r, ctx) => {
    // ctx.context.env is typed as 'dev' | 'staging' | 'prod'
  },
});

Interactive When You Need It

Missing a required flag? pok prompts for it. No more hunting through --help output:

$ mycli deploy
? Select environment › dev / staging / prod

Beautiful Output

Structured output with spinners, progress indicators, and grouped activities—powered by adapters so you choose your UI:

await r.group('Database Setup', async (g) => {
  await g.activity('Running migrations', async () => {
    await r.exec('prisma migrate deploy');
  });
});

Parallel & Tabbed Execution

Run multiple processes side-by-side with a tabbed terminal interface:

await r.tabs([r.exec('vite dev'), r.exec('stripe listen'), r.exec('inngest dev')]);

Composable Tasks

Define reusable units of work with their own environment requirements:

const migrate = defineTask({
  label: 'Run migrations',
  env: databaseEnv,
  exec: () => 'prisma migrate deploy',
});

// Use in any command
await r.run(migrate);

Quick Start

# Create a new project
bun create pokit my-cli

# Or add to existing project
bun add @pokit/core zod

Packages

Package	Description
@pokit/core	Core framework—command routing, task execution, event system
pokit	Global CLI launcher—install once, run anywhere
create-pokit	Project scaffolding CLI
@pokit/op	Operation utilities for common CLI patterns
@pokit/prompter-clack	Interactive prompts adapter (Clack)
@pokit/reporter-clack	Terminal output adapter (Clack)
@pokit/tabs-core	Shared tabs state management
@pokit/tabs-ink	Tabbed terminal UI (Ink/React)
@pokit/tabs-opentui	Tabbed terminal UI (OpenTUI/React)

Documentation

• Getting Started
• Architecture
• API Reference
• Concepts

License

MIT