Static copy

Copied from docs/en/getting-started/cli-overview.md in https://github.com/poppy-team/aipo-lang (MIT). Pinned to revision ce47c4e070404fc41722ccd8e2b7b808b99062a8, blob ba15b2452e3e319e339bce70c68c08565a153510. The source repository remains canonical; this copy is refreshed through a sync pull request, not live.

Command-Line Interface Guide (aipo)

The aipo executable is the unified toolchain utility for execution, static checking, JavaScript code generation, bytecode disassembly, code formatting, and hermetic package auditing.

---

Primary Subcommands

aipo run

Compiles and executes an Aipo source file (.aipo) or precompiled bytecode (.aibc):

# Run source file directly
aipo run src/main.aipo

# Run with custom package cache directory
aipo run src/main.aipo --package-cache .aipo/cache

# Structured JSONL diagnostic output (ideal for IDEs and CI pipelines)
aipo run src/main.aipo --message-format=jsonl

aipo test

Discovers and executes unit tests automatically across *_test.aipo and test_*.aipo files, with full isolation, zeroed PRNG seeds, and a frozen virtual clock:

# Run all unit tests
aipo test

# Filter tests by name or path pattern
aipo test --filter math

# Machine-readable streaming JSONL for CI/CD
aipo test --message-format=jsonl

aipo check

Runs the complete static analysis pipeline (Lexer, Parser, HIR, SEMA, and bytecode verification) without running the VM:

aipo check src/main.aipo

Accurately reports syntax errors, incompatible interface contracts, unbound variable references, and illegal mutations of immutable fields.

aipo build

Emits the complete JavaScript bundle (app.js, aipo-runtime.js, and app.js.map sourcemap) ready for deployment in modern browsers or Node.js runtimes:

# Compile and emit bundle into output directory
aipo build src/main.aipo --out dist/

aipo disasm

Disassembles an .aipo or .aibc file, displaying VM instructions, byte offsets, constant pool entries, and mapped source coordinates:

aipo disasm src/main.aipo

aipo fmt

Formats Aipo source files according to canonical language style conventions:

# Format files in place
aipo fmt src/main.aipo

# Verify formatting without writing changes (CI mode)
aipo fmt --check src/

aipo package

Hermetic commands for package management, lockfile generation, and security auditing:

# Create or update deterministic lockfile (aipo.lock)
aipo package lock .

# Create lockfile fetching remote GitHub snapshots into local cache
aipo package lock . --fetch-github --cache .aipo/cache

# Audit integrity and manifest compliance of a local package
aipo package audit .

# Verify cryptographic SHA-256 integrity across all cached entries
aipo package cache verify .aipo/cache

# Prune unreferenced, stale cache entries safely
aipo package cache prune .aipo/cache --lock aipo.lock --apply

📖 Comprehensive Tooling Guide

For in-depth details on compiler flags, WebAssembly targets, CI/CD integrations, and real-world examples, visit the Complete Developer Tooling Guide.