Skip to main content

​
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 install 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: 
npx tsx 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:
mkdir my-cli
cd my-cli
npm init -y
npm install incur typescript tsx
  1. 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"
  }
}
  1. 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
  1. 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

Ensure your package.json has "type": "module" and your tsconfig.json uses "module": "ESNext".
incur re-exports Zod, so always import from incur:
// ✅ Correct
import { Cli, z } from 'incur'

// ❌ Wrong
import { z } from 'zod'
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

Build docs developers (and LLMs) love

Get started for freeTalk to us