Creating a Standalone CLI

While pok provides a global launcher for quick scripts, you can also use @pokit/core to build and distribute your own standalone CLI applications with their own binary name (e.g., my-tool).

1. Project Setup

Create a new directory for your CLI and initialize it:

mkdir my-tool && cd my-tool
bun init -y

Install the core framework and the default terminal UI:

bun add @pokit/core zod @pokit/terminal

2. Create the Entry Point

Create a bin/cli.ts file. This will be the main script your users run.

#!/usr/bin/env bun
import { runCli } from '@pokit/core';
import { createTerminalUI } from '@pokit/terminal';
import * as path from 'path';
import { fileURLToPath } from 'url';

// Get the directory where this script is located.
// Use fileURLToPath — `new URL(import.meta.url).pathname` leaves the path
// percent-encoded, so it breaks under directories containing spaces.
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const projectRoot = path.resolve(__dirname, '..');

const { reporter, prompter, navigator } = createTerminalUI();

await runCli(process.argv.slice(2), {
  appName: 'my-tool',
  version: '1.0.0',
  // Point to your commands directory
  commandsDir: path.join(projectRoot, 'commands'),
  projectRoot: projectRoot,
  // Attach the default terminal UI surfaces
  prompter,
  reporterAdapter: reporter,
  navigator,
});

Make it executable:

chmod +x bin/cli.ts

3. Define Commands

Create a commands/ directory and add your first command:

// commands/hello.ts
import { defineCommand } from '@pokit/core';

export const command = defineCommand({
  label: 'Say hello',
  run: async (r) => {
    r.reporter.info('Hello from my standalone tool!');
  },
});

4. Configure Package Distribution

Add a bin field to your package.json so users can install it globally or run it via package managers.

{
  "name": "my-tool",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "my-tool": "./bin/cli.ts"
  },
  "dependencies": {
    "@pokit/core": "latest",
    "@pokit/terminal": "latest"
  }
}

5. Distribution

Via NPM/Registry

Publish your package to an NPM-compatible registry:

npm publish

Your users can then install and run it:

npm install -g my-tool
my-tool hello

As a Standalone Binary

You can use Bun to compile your CLI into a single, zero-dependency executable for distribution:

# Compile for the current platform
bun build ./bin/cli.ts --compile --outfile my-tool

# Or cross-compile for other platforms
bun build ./bin/cli.ts --compile --target=bun-linux-x64 --outfile my-tool-linux

Your users can now run the my-tool binary directly without needing Bun or Node.js installed.

PreviousTestingNextDynamic Menus