npm package: @intend-it/cli
Description: CLI for the Intend programming language
Latest version: 1.3.4

<div align="center">
  <h1>@intend-it/cli</h1>
  <p><strong>Command-Line Interface for the Intend Programming Language</strong></p>
  <p>
    <a href="https://intend.fly.dev">Documentation</a> •
    <a href="https://www.npmjs.com/package/@intend-it/cli"><img src="https://img.shields.io/npm/v/@intend-it/cli.svg" alt="npm version"></a>
    <a href="https://www.npmjs.com/package/@intend-it/cli"><img src="https://img.shields.io/npm/dm/@intend-it/cli.svg" alt="npm downloads"></a>
    <a href="https://github.com/DRFR0ST/intend/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@intend-it/cli.svg" alt="license"></a>
  </p>
</div>

---

## Overview

The official CLI for building **Intend** projects. Write your intentions, let AI generate the code.

**[Read the full documentation 📖](https://intend.fly.dev)**

### ✨ Features

- **🚀 Zero Config** - Works out of the box with sensible defaults
- **⚡ Instant Builds** - Smart caching means unchanged files build instantly
- **🔄 Watch Mode** - Auto-rebuild on file changes
- **🤖 AI Providers** - Supports Gemini and Ollama (local)
- **🛡️ Self-Healing** - Auto-corrects AI mistakes with validation loop

## Installation

```bash
# Global install
npm install -g @intend-it/cli

# Or use with npx/bunx
npx @intend-it/cli build
bunx @intend-it/cli build
```

## Quick Start

```bash
# 1. Create a new project
intend init my-app
cd my-app

# 2. Set your API key
export GEMINI_API_KEY="your-key-here"

# 3. Build!
intend build
```

## Commands

### `intend init [directory]`

Initialize a new Intend project with configuration and example files.

```bash
intend init my-project
intend init .  # Current directory
```

Creates:
- `intend.config.json` - Project configuration
- `src/intents/` - Directory for `.intent` files
- `out/` - Output directory for generated TypeScript
- `intend.lock` - Deterministic build lockfile (commit this!)

### 🔒 Build Lockfile (`intend.lock`)

To ensure that your builds are deterministic and fast, Intend uses a lockfile system. 

When you run `intend build`, the CLI calculates a hash of your `.intent` source code and your configuration. If a match is found in `intend.lock`, the compiler uses the cached implementation instead of calling the AI provider.

- **Fast Rebuilds**: Near-instant builds for unchanged files.
- **Stable Production**: Your code won't change in CI/CD unless you explicitly change the intention.
- **Version Control**: You should always commit `intend.lock` to your repository.

### `intend build`

Build all `.intent` files in your project.

```bash
intend build                    # Build with default config
intend build --force            # Ignore cache, rebuild all
intend build --attempts=10      # Set retry limit
intend build --provider=ollama  # Use Ollama instead of Gemini
```

**Options:**
| Flag | Description |
|------|-------------|
| `--config <path>` | Custom config file path |
| `--output <dir>` | Override output directory |
| `--provider <name>` | AI provider: `gemini` or `ollama` |
| `--api-key <key>` | Gemini API key |
| `--force` | Ignore cache, rebuild everything |
| `--attempts <n>` | Max auto-correction retries (default: 5) |

### `intend watch`

Watch for changes and auto-rebuild.

```bash
intend watch
```

### `intend parse <file>`

Parse a single file and output AST/CST (useful for debugging).

```bash
intend parse src/intents/user.intent --ast
intend parse src/intents/user.intent --cst
```

## Configuration

Create `intend.config.json` in your project root:

```json
{
  "sourceDir": "./src/intents",
  "outDir": "./out",
  "provider": "gemini",
  "gemini": {
    "apiKey": "${GEMINI_API_KEY}",
    "model": "gemini-2.0-flash",
    "temperature": 0.2
  }
}
```

### Using Ollama (Local AI)

```json
{
  "sourceDir": "./src/intents",
  "outDir": "./out",
  "provider": "ollama",
  "ollama": {
    "model": "llama3",
    "baseUrl": "http://localhost:11434",
    "num_thread": 4
  }
}
```

## Example Workflow

**1. Write an intent file** (`src/intents/math.intent`):

```typescript
export intent Add(a: number, b: number) -> number {
    invariant "Both inputs must be numbers"
    step "Add the two numbers together" => const result
    ensure result is a number
}

export intent Multiply(a: number, b: number) -> number {
    step "Multiply the numbers" => const product
    ensure product is a number
}
```

**2. Build:**

```bash
$ intend build

✨ Intend Build

  Source   ./src/intents
  Output   ./out
  Provider gemini

◐ Scanning for .intent files...
  ✔ Found 1 intent file

Compiling

  ✔ math.intent 1247ms

Summary

  ✔ 1 compiled
  → 1.25s
```

**3. Use the generated code:**

```typescript
import { Add, Multiply } from "./out/math";

const sum = Add(5, 3);      // 8
const product = Multiply(4, 7); // 28
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `GEMINI_API_KEY` | Google Gemini API key |
| `INTEND_PROVIDER` | Default provider (`gemini` or `ollama`) |

## Related Packages

- [`@intend-it/parser`](https://www.npmjs.com/package/@intend-it/parser) - Lexer and parser
- [`@intend-it/core`](https://www.npmjs.com/package/@intend-it/core) - AI code generator

## License

MIT © [Intend Team](https://github.com/DRFR0ST/intend)