Getting started

This guide takes you from an empty terminal to a verified generated edition.

Before you begin

Make sure you have:

• Node.js 18 or newer
• Python 3.9 or newer for the current Angl CLI package
• A compiler provider: Codex, Claude Code, or Ollama

Install and log in to the provider you want to use. Codex support uses codex exec; Claude Code support uses claude -p; Ollama support uses a local model server.

Python is not the required language for generated code. It is required today because the current Angl parser, CLI, fixtures, repair loop, and judge are implemented in Python. A chapter can still compile to another target such as Node, Ruby, Go, Rust, TypeScript, bundle, or assembly.

Step 1: Install Angl

Install the CLI globally:

npm install -g angl-cli

You can use another package manager if that is how your machine is set up:

pnpm add -g angl-cli
bun add -g angl-cli

Prove the installed command and compiler provider work:

angl try --provider claude-code

angl try creates a temporary starter project, configures the provider only inside that project, checks the source, runs a provider smoke request, compiles, and verifies the examples. It removes the temporary project after a green run.

Use --provider codex if you want Codex, but run it from a normal terminal. Nested Codex sessions can block codex exec.

Step 2: Connect a compiler provider

For a real project, save your provider once:

angl setup codex
angl doctor --provider-smoke

If you use Claude Code:

angl setup claude-code
angl doctor --provider-smoke

If you use Ollama:

angl setup ollama --model qwen2.5-coder:14b --url http://127.0.0.1:11434
angl doctor --provider-smoke

Provider choice is toolchain configuration. It is not part of the .angl language.

Step 3: Create a project

angl new hello-angl
cd hello-angl

The starter project contains one source chapter and editor tasks. It defaults to Python because that is the most mature target today, but target choice is a chapter setting, not a language requirement.

To make a chapter generate JavaScript, set its target:

> Runs as: `node`

That chapter still stays English behavior plus executable examples. The generated edition becomes a .js artifact under build/, and the same black-box judge decides whether it is accepted.

Step 4: Compile and verify

angl build

Angl loads the target chapter, compiles dependencies first, writes generated output into build/, and runs the black-box judge against every example.

For a Node chapter, the generated file is JavaScript. For a Ruby chapter, it is Ruby. For Docker-backed targets such as Go, Rust, and TypeScript, Angl uses generated adapter plumbing to keep the judge language-neutral.

To verify an existing generated edition without asking the compiler provider for new code:

angl verify

Step 5: Read the generated edition

Generated code is build output, not source. It lives in build/ and can be inspected when you need to debug or review what the compiler produced.

ls build

Each generated artifact also has a manifest next to it with provider, attempt, target, and generated-file metadata.

Step 6: Preview a chapter

Render the current chapter as a readable source view:

angl preview --serve --view chapter

The preview is for reading and review. The committed source is still the .angl file.

The normal workflow

Whether the author is a human or an agent, the loop is:

edit .angl
angl check
angl build
inspect build/ when needed
commit the .angl change

If behavior changes, the examples in the chapter change with it. Untested behavior is unspecified behavior.

Working on the Angl repo itself

If you are developing the toolchain instead of using the installed CLI, clone the repo and run the modules directly:

python3 -m venv .venv
.venv/bin/python3 -m pip install -r requirements.txt
python3 -m angl.cli check specs/provision_service.angl
python3 -m angl.cli build specs/provision_service.angl

Toolchain tests do not require a model:

python3 tests/test_parse.py
python3 tests/test_verify.py
python3 tests/test_compile.py
python3 tests/test_run.py
python3 tests/test_book.py