Overview

The official CLI for building Intend projects. Write your intentions, let AI generate the code.

Read the full documentation 📖

✨ 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

# 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

# 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.

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.

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.

intend watch

intend parse <file>

Parse a single file and output AST/CST (useful for debugging).

intend parse src/intents/user.intent --ast
intend parse src/intents/user.intent --cst

Configuration

Create intend.config.json in your project root:

{
  "sourceDir": "./src/intents",
  "outDir": "./out",
  "provider": "gemini",
  "gemini": {
    "apiKey": "${GEMINI_API_KEY}",
    "model": "gemini-2.0-flash",
    "temperature": 0.2
  }
}

Using Ollama (Local AI)

{
  "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):

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:

$ 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:

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 - Lexer and parser
• @intend-it/core - AI code generator

License

MIT © Intend Team