Getting Started

Launch your CLI development journey with Rempts. This guide demonstrates how to scaffold, configure, and build your first Bun-native command-line application in minutes.

Prerequisites

Rempts is exclusively designed for Bun runtime. Ensure you have Bun 1.0 or later installed from bun.sh

# Verify your Bun installation
bun --version

Quick Start

Scaffold your CLI project

Leverage the intelligent scaffolding tool to bootstrap your CLI:

bunx @reliverse/rempts my-cli
cd my-cli

The interactive setup will prompt for:

Project name: Validated identifier using lowercase letters, numbers, and hyphens
Template: Select from basic (minimal), advanced (feature-rich), or monorepo (workspace)
Package manager: Choose your preferred package manager (bun, npm, yarn, pnpm)

The scaffolding automatically handles:

✅ Structured project layout with file-based command discovery
✅ Git repository initialization with appropriate ignores
✅ Dependency installation including @reliverse/rempts-core
✅ TypeScript configuration optimized for Bun
✅ Comprehensive testing setup with Bun's test runner
✅ Generated dler.config.ts with sensible defaults

Understand the project layout

Rempts generates a production-ready project structure optimized for Bun:

my-cli/
├── cli.ts                # Main entry point with async CLI initialization
├── cmds/                 # Command directory (essential for file-based discovery)
│   └── greet/
│       └── cmd.ts        # Individual command implementations
├── dler.config.ts        # Auto-loaded configuration file
├── package.json          # Dependencies with @reliverse/rempts-core
├── tsconfig.json         # Bun-optimized TypeScript configuration
└── README.md             # Generated project documentation

Launch your CLI

Execute your CLI directly using Bun's native TypeScript support:

bun run cli.ts --help

Execute directly using Bun's native TypeScript support:

bun run cli.ts --help

Implement your first command

Define a greeting command in cmds/greet/cmd.ts with type-safe options:

import { defineCommand, option } from '@reliverse/rempts-core'
import { z } from 'zod'

export default defineCommand({
  name: 'greet',
  description: 'Greet someone',
  options: {
    name: option(
      z.string().min(1),
      { description: 'Name to greet', short: 'n' }
    ),
    excited: option(
      z.coerce.boolean().default(false),
      { description: 'Add excitement', short: 'e' }
    )
  },
  handler: async ({ flags, prompt, spinner, colors }) => {
    const spin = spinner('Preparing greeting...')
    spin.start()

    let name = flags.name
    if (!name) {
      name = await prompt('What is your name?')
    }

    spin.succeed()

    const greeting = colors.green(
      `Hello, ${name}${flags.excited ? '!' : '.'}`
    )
    console.log(greeting)
  }
})

import { defineCommand, option } from '@reliverse/rempts-core'
import { type } from 'arktype'

export default defineCommand({
  name: 'greet',
  description: 'Greet someone',
  options: {
    name: option(
      type('string > 0'),
      { description: 'Name to greet', short: 'n' }
    ),
    excited: option(
      type('boolean').pipe(b => b ?? false),
      { description: 'Add excitement', short: 'e' }
    )
  },
  handler: async ({ flags, prompt, spinner, colors }) => {
    const spin = spinner('Preparing greeting...')
    spin.start()

    let name = flags.name
    if (!name) {
      name = await prompt('What is your name?')
    }

    spin.succeed()

    const greeting = colors.green(
      `Hello, ${name}${flags.excited ? '!' : '.'}`
    )
    console.log(greeting)
  }
})

Test your implementation

Execute the command through the development server:

# Test with development server
bunx @reliverse/rempts dev greet --name World --excited
# Output: Hello, World!

# Execute the full test suite
bunx @reliverse/rempts test

Compile for distribution

Generate optimized, standalone executables ready for deployment:

# Compile for current platform
bunx @reliverse/rempts build

# Cross-compile for all supported platforms
bunx @reliverse/rempts build --all

Template Selection

Choose from curated project templates designed for different CLI complexity levels:

Minimal CLI foundation for getting started:

bunx @reliverse/rempts my-cli --template basic

Ideal for:

Rempts fundamentals exploration
Utility scripts and automation
Focused single-purpose applications

Provides:

Bun-optimized TypeScript configuration
Sample command with comprehensive tests
Production build pipeline setup

Full-featured CLI with comprehensive capabilities:

bunx @reliverse/rempts my-cli --template advanced

Features:

Multi-command architecture (init, validate, serve, config)
Advanced configuration management system
Integrated file validation utilities
Built-in development server
Interactive license selection workflow

Suited for:

Enterprise-grade CLI applications
Developer productivity tools
Sophisticated command-line interfaces

Scalable workspace configuration for complex projects:

bunx @reliverse/rempts my-cli --template monorepo

Capabilities:

Turborepo-powered build orchestration
Multi-package workspace structure (cli, core, utils)
Automated versioning with Changesets
Parallel build execution and caching

Designed for:

Large development teams
Multi-package CLI ecosystems
Enterprise-scale architectures

Custom Templates

Leverage any GitHub repository or NPM package as your project foundation:

# Use a GitHub repository template
bunx @reliverse/rempts my-cli --template username/repo

# Specify a particular branch
bunx @reliverse/rempts my-cli --template username/repo#branch

# Utilize an NPM-published template
bunx @reliverse/rempts my-cli --template npm:template-package

Manual Configuration

For complete control over your CLI setup, configure Rempts manually:

Install core dependencies

bun add @reliverse/rempts-core @reliverse/rempts-utils

Establish the main entry point

// cli.ts
import { createCLI } from '@reliverse/rempts-core'

const cli = await createCLI({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My awesome CLI'
})

// CLI automatically discovers commands via dler.config.ts
await cli.run()

Configure package.json

{
  "name": "my-cli",
  "bin": {
    "my-cli": "./cli.ts"
  },
  "scripts": {
    "dev": "bunx @reliverse/rempts dev",
    "build": "bunx @reliverse/rempts build",
    "test": "bun test"
  },
  "dependencies": {
    "@reliverse/rempts-core": "latest",
    "@reliverse/rempts-utils": "latest"
  }
}

Configure dler.config.ts

import { defineConfig } from '@reliverse/rempts-core'

export default defineConfig({
  name: 'my-cli',
  version: '1.0.0',
  description: 'My awesome CLI',
  commands: {
    directory: './commands' // Activate file-based command discovery
  }
})

The commands.directory configuration enables automatic command discovery, where Rempts scans your cmds directory and converts each cmd.{ts,js,mjs} file into a command. Nested directories establish command hierarchies (e.g., cmds/db/migrate/cmd.ts becomes my-cli db migrate).

Establish commands directory

mkdir commands

// cmds/hello/cmd.ts
import { defineCommand } from '@reliverse/rempts-core'

export default defineCommand({
  name: 'hello',
  description: 'Say hello',
  handler: async ({ colors }) => {
    console.log(colors.green('Hello from Rempts!'))
  }
})

Continue Your Journey

With your CLI foundation established, explore advanced capabilities:

Master Command Architecture - Core building blocks of CLI applications
Harness Automatic Type Inference - Maximize TypeScript productivity
Implement Schema Validation - Ensure robust input handling
Develop Comprehensive Tests - Maintain CLI reliability
Master Distribution & Deployment - Share your CLI globally

Connect with the community on GitHub Discussions for support and inspiration!

Getting Started

On this page