Overview

This guide walks you through installing the Aiken CLI and configuring your development environment. After completing these steps, you can write, compile, and test Aiken smart contracts.

Prerequisites:

macOS, Linux, or Windows with WSL
A code editor (VS Code recommended)
Node.js 18+ for Mesh integration

Quick Start

Install Aiken and verify your setup in under 5 minutes.

# Install Aiken (macOS/Linux)
curl -sSfL https://install.aiken-lang.org | bash
aikup

# Verify installation
aiken --version

Step-by-Step Installation

Option 1: Using aikup (macOS and Linux)

The aikup utility downloads and manages Aiken versions. This is the recommended installation method.

Step 1: Install aikup

curl -sSfL https://install.aiken-lang.org | bash

Step 2: Install the latest Aiken version

aikup

Step 3: Verify installation

aiken --version

You should see output like aiken v1.x.x.

Option 2: Build from Source (All Platforms)

Build Aiken from source using Cargo. This method works on all platforms including Windows.

Step 1: Install Rust

If you don't have Rust installed, get it from rustup.rs.

# Verify Rust installation
rustc --version
cargo --version

Step 2: Install Aiken via Cargo

cargo install aiken

Step 3: Verify installation

aiken --version

Editor Setup

VS Code Extension

Install the Aiken extension for syntax highlighting, code snippets, and error checking.

Installation options:

Search for "aiken" in the VS Code Extensions tab
Or install directly from the VS Code Marketplace

Features:

Syntax highlighting for .ak files
Inline error checking
Code snippets for common patterns
Go-to-definition support

CLI Reference

Use these commands to develop and test your smart contracts.

aiken new

Create a new Aiken project with the standard directory structure.

aiken new your-org/project-name
cd project-name

aiken build

Compile your validators and generate the plutus.json blueprint file.

aiken build

The blueprint contains:

Compiled validator code (CBOR-encoded)
Type information for datum and redeemer
Hash digests for each validator

aiken check

Type-check your project and run tests.

aiken check

Use this command frequently during development to catch errors early.

aiken docs

Generate HTML documentation from your project's comments.

aiken docs

aiken blueprint

Utility functions for working with the compiled blueprint.

# Generate an address for a validator
aiken blueprint address

# Convert blueprint to different formats
aiken blueprint convert

Complete Example

Create a new project and verify the setup.

# Create project
aiken new meshjs/hello_world
cd hello_world

# Check the project structure
ls -la

# Run the type checker
aiken check

# Build the project
aiken build

# Verify the blueprint was generated
cat plutus.json

Project Structure

After running aiken new, your project looks like this:

hello_world/
  aiken.toml          # Project configuration
  lib/                # Shared library code
  validators/         # Validator scripts
  plutus.json         # Generated blueprint (after build)

Key files:

aiken.toml - Project metadata and dependencies
validators/*.ak - Your validator scripts
plutus.json - Compiled output for use with Mesh

Troubleshooting

Command not found: aiken

The Aiken binary is not in your PATH. Add it manually:

# For aikup installations
export PATH="$HOME/.aiken/bin:$PATH"

# Add to your shell profile for persistence
echo 'export PATH="$HOME/.aiken/bin:$PATH"' >> ~/.bashrc

Build fails with type errors

Run aiken check to see detailed error messages. Common issues:

Missing imports - Add required modules at the top of your file
Type mismatches - Verify datum/redeemer types match your validator signature
Syntax errors - Check for missing commas or brackets

VS Code extension not working

Reload VS Code after installing the extension
Verify the file has a .ak extension
Check the extension is enabled for the workspace

plutus.json not generating

Ensure your project has at least one validator in the validators/ directory. Empty projects don't generate a blueprint.

Write Your First Smart Contract - Create a validator
Build Transactions - Interact with contracts using Mesh
Aiken Language Tour - Learn Aiken syntax
Official Installation Guide - More installation options

Getting Started