Getting Started

This guide walks you through installing ThinkLang and running your first AI-powered program using the CLI and .tl files.

Looking for the JS/TS library?

If you want to use ThinkLang's AI primitives directly from JavaScript or TypeScript without writing .tl files, see the Library Quick Start.

Prerequisites

• Node.js 18+ (LTS recommended)
• An API key from any supported provider: Anthropic, OpenAI, Google Gemini, or a local Ollama server

Installation

Install ThinkLang globally from npm:

npm install -g thinklang

Or run it directly without installing:

npx thinklang run hello.tl

Environment Setup

Set an API key for your preferred provider as an environment variable:

# Anthropic (default)
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Or OpenAI
export OPENAI_API_KEY=sk-your-key-here

# Or Google Gemini
export GEMINI_API_KEY=AIyour-key-here

# Or Ollama (local, no API key needed)
export OLLAMA_BASE_URL=http://localhost:11434

You can also create a .env file in your project directory:

ANTHROPIC_API_KEY=sk-ant-your-key-here
THINKLANG_MODEL=claude-opus-4-6
THINKLANG_CACHE=true

Variable	Required	Default	Description
ANTHROPIC_API_KEY	One of these	--	Anthropic API key
OPENAI_API_KEY	One of these	--	OpenAI API key
GEMINI_API_KEY	One of these	--	Google Gemini API key
OLLAMA_BASE_URL	One of these	--	Ollama server URL
THINKLANG_MODEL	No	claude-opus-4-6	Model to use for AI calls
THINKLANG_CACHE	No	true	Cache identical AI requests

ThinkLang auto-detects which provider to use from the environment variable that is set. See the Provider System guide for details.

Your First Program

Create a file called hello.tl:

let greeting = think<string>("Say hello to the world in a creative way")
print greeting

Run it:

thinklang run hello.tl

The think keyword calls an LLM and returns a typed result. Here we asked for a string, so that is exactly what we get back.

A Structured Example

ThinkLang shines when you define types for AI outputs. Create classify.tl:

type Classification {
  @description("The category of the email")
  category: string
  @description("Confidence score from 0 to 1")
  confidence: float
  @description("Brief explanation")
  reason: string
}

let email = "Congratulations! You've won a FREE iPhone! Click here now!"

let result = think<Classification>("Classify this email as spam, promotional, personal, or work")
  with context: email

print result

The AI returns a structured Classification object with exactly the fields you defined.

CLI Commands

Command	Description
thinklang run <file.tl>	Run a ThinkLang program
thinklang compile <file.tl>	Emit compiled TypeScript to stdout
thinklang repl	Start an interactive REPL session
thinklang test [target]	Run .test.tl test files
thinklang cost-report	Show cost summary for the current session

Useful Flags

• thinklang run --show-cost -- Print a cost summary after execution
• thinklang compile -o output.ts -- Write compiled output to a file
• thinklang test --replay -- Run tests using recorded snapshots
• thinklang test --update-snapshots -- Record live responses to snapshot files
• thinklang test --pattern <regex> -- Filter test files by pattern

Splitting Code Across Files

As your programs grow, use import to share types and functions between files:

// types.tl
type Sentiment {
  label: string
  score: float
}

// main.tl
import { Sentiment } from "./types.tl"

let result = think<Sentiment>("Analyze sentiment of this review")
  with context: review
print result

All top-level type and fn declarations are automatically importable -- no export keyword is needed.

Next Steps

• Take the Language Tour for a quick overview of all features
• Learn about the Type System
• Explore AI Primitives: think, infer, and reason
• Build agentic workflows with Agents & Tools
• Process collections with Big Data
• Use ThinkLang as a JS/TS Library