> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wevm/incur/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Get started with incur in your project

## System Requirements

<Info>
  incur requires **Node.js 18.0.0 or later** and **TypeScript 5.0 or later**.
</Info>

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:

<CodeGroup>
  ```bash npm theme={null}
  npm install incur
  ```

  ```bash pnpm theme={null}
  pnpm add incur
  ```

  ```bash bun theme={null}
  bun add incur
  ```
</CodeGroup>

## Verify Installation

Create a simple test file to verify incur is working:

```typescript test.ts theme={null}
import { Cli, z } from 'incur'

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

cli.serve()
```

Run it:

<CodeGroup>
  ```bash tsx theme={null}
  npx tsx test.ts
  ```

  ```bash ts-node theme={null}
  npx ts-node test.ts
  ```

  ```bash bun theme={null}
  bun test.ts
  ```
</CodeGroup>

You should see:

```
status: ok
```

<Tip>
  Use `tsx` for the fastest TypeScript execution without compilation.
</Tip>

## TypeScript Configuration

incur works best with these `tsconfig.json` settings:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}
```

<Note>
  The `moduleResolution: "bundler"` setting is recommended for best compatibility with incur's ESM exports.
</Note>

## Project Setup

### For a new CLI project

1. Initialize your project:

<CodeGroup>
  ```bash npm theme={null}
  mkdir my-cli
  cd my-cli
  npm init -y
  npm install incur typescript tsx
  ```

  ```bash pnpm theme={null}
  mkdir my-cli
  cd my-cli
  pnpm init
  pnpm add incur typescript tsx
  ```

  ```bash bun theme={null}
  mkdir my-cli
  cd my-cli
  bun init
  bun add incur
  ```
</CodeGroup>

2. Update `package.json`:

```json package.json theme={null}
{
  "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:

```typescript src/index.ts theme={null}
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:

```bash theme={null}
npm run dev -- --help
```

### For an existing project

Simply install incur and import it:

```bash theme={null}
npm install incur
```

```typescript theme={null}
import { Cli, z } from 'incur'
```

## Build and Distribution

### Compile to JavaScript

Build your CLI for distribution:

```bash theme={null}
npm run build
```

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

```bash theme={null}
node dist/index.js --help
```

### Test locally

Link your CLI globally for testing:

```bash theme={null}
npm link
```

Now you can run it from anywhere:

```bash theme={null}
my-cli --help
```

<Warning>
  Remember to `npm unlink` when done testing to avoid conflicts.
</Warning>

### Publish to npm

Once ready, publish your CLI:

```bash theme={null}
npm publish
```

Users can then install and use it:

```bash theme={null}
npm install -g my-cli
my-cli --help
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Module not found errors">
    Ensure your `package.json` has `"type": "module"` and your `tsconfig.json` uses `"module": "ESNext"`.
  </Accordion>

  <Accordion title="Zod import errors">
    incur re-exports Zod, so always import from `incur`:

    ```typescript theme={null}
    // ✅ Correct
    import { Cli, z } from 'incur'

    // ❌ Wrong
    import { z } from 'zod'
    ```
  </Accordion>

  <Accordion title="TypeScript errors with generics">
    Make sure you're using TypeScript 5.0 or later. incur relies on modern TypeScript features for type inference.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Tutorial" icon="rocket" href="/quickstart">
    Build your first CLI with commands and options
  </Card>

  <Card title="Core Concepts" icon="book" href="/core-concepts/cli-creation">
    Learn about commands, schemas, and output formats
  </Card>
</CardGroup>