Installation

Get started with incur in your project

System Requirements

incur requires Node.js 18.0.0 or later and TypeScript 5.0 or later.

Before installing, ensure you have:

• Node.js 18+ (check with node --version)
• A package manager (npm, pnpm, or bun)
• TypeScript 5.0+ in your project

Install incur

Choose your package manager:

npm

npm install incur

pnpm add incur

bun add incur

Verify Installation

Create a simple test file to verify incur is working:

test.ts

import { Cli, z } from 'incur'

const cli = Cli.create('test', {
  description: 'Test CLI',
  run() {
    return { status: 'ok' }
  },
})

cli.serve()

Run it:

tsx

npx tsx test.ts

npx ts-node test.ts

bun test.ts

You should see:

status: ok

Use tsx for the fastest TypeScript execution without compilation.

TypeScript Configuration

incur works best with these tsconfig.json settings:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

The moduleResolution: "bundler" setting is recommended for best compatibility with incur’s ESM exports.

Project Setup

For a new CLI project

1. Initialize your project:

npm

mkdir my-cli
cd my-cli
npm init -y
npm install incur typescript tsx

mkdir my-cli
cd my-cli
pnpm init
pnpm add incur typescript tsx

mkdir my-cli
cd my-cli
bun init
bun add incur

2. Update package.json:

package.json

{
  "name": "my-cli",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "my-cli": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

3. Create your CLI entry point:

src/index.ts

import { Cli, z } from 'incur'

const cli = Cli.create('my-cli', {
  version: '1.0.0',
  description: 'My awesome CLI',
})

cli.serve()

export default cli

4. Run in development:

npm run dev -- --help

For an existing project

Simply install incur and import it:

npm install incur

import { Cli, z } from 'incur'

Build and Distribution

Compile to JavaScript

Build your CLI for distribution:

npm run build

This creates dist/index.js which can be executed directly:

node dist/index.js --help

Test locally

Link your CLI globally for testing:

npm link

Now you can run it from anywhere:

my-cli --help

Remember to npm unlink when done testing to avoid conflicts.

Publish to npm

Once ready, publish your CLI:

npm publish

Users can then install and use it:

npm install -g my-cli
my-cli --help

Troubleshooting

Module not found errors

Ensure your package.json has "type": "module" and your tsconfig.json uses "module": "ESNext".

Zod import errors

incur re-exports Zod, so always import from incur:

// ✅ Correct
import { Cli, z } from 'incur'

// ❌ Wrong
import { z } from 'zod'

TypeScript errors with generics

Make sure you’re using TypeScript 5.0 or later. incur relies on modern TypeScript features for type inference.

Next Steps

Quickstart Tutorial

Build your first CLI with commands and options

Core Concepts

Learn about commands, schemas, and output formats