izi — the IZI language CLI

The compiler CLI for IZI, the easy AI orchestration language. IZI is Markdown-native: every .izi.md file is simultaneously documentation and an executable AI artifact — a prompt, a workflow, an agent, or a skill (see IZI_SPEC.md v1.0).

izi compiles those artifacts into deployable code you can push inside any customer environment — and decompiles them back to the original .izi.md, losslessly.

izi compile agent-prospection.izi.md --mastra   # → agent-prospection.mastra.ts
izi compile weekly-digest.izi.md --py           # → weekly-digest.py
izi decompile agent-prospection.mastra.ts       # → agent-prospection.izi.md (exact source)

Installation

npm install -g izi
# or
npx izi <command>

Compile

izi compile <file.izi.md> [target] [options]

| Target | Flag | Output | |---|---|---| | Plain Node.js | --js (default) | Self-contained script on @anthropic-ai/sdk implementing the full step tree (@if, @foreach, @parallel, @try/@catch, @ask) | | Plain Python | --py | Same semantics on the anthropic SDK with asyncio | | Mastra (TypeScript) | --mastra | Agent / createWorkflow artifacts on @mastra/core; @ask maps to Mastra suspend/resume |

Options: -t, --target <id> (explicit form), -o, --out <path>, --ir <path> (also write the compiled RunSpec IR as JSON), -f, --force.

What the compiler does (per IZI_SPEC v1.0):

• Detects the artifact kind from the file's top-level blocks (§3): one @prompt → prompt, several/control flow → workflow, @agent → agent, @skill → skill
• Builds the step tree: @prompt/@step, @if/@else, @foreach, @parallel, @try/@catch, @run (sub-runs), @ask (human-in-the-loop)
• Derives the run-input schema from typed variables ($email:string:email:required) and undeclared $vars (§L7)
• Collects tool requirements (%email, %gmail::composio) — generated as explicit deny-by-default stubs; the file never contains auth (§6)
• Validates composition (@include / @use / @run refs, cycles, depth) and the closed @config key set, with IZI-E-* / IZI-W-* diagnostics

Every generated artifact embeds its original source in the header banner, which is what makes decompilation lossless.

Decompile

izi decompile <generated-file> [-o out.izi.md]

Recovers the exact .izi.md source from anything izi compile produced (any language), or from an --ir JSON file. Your IZI source travels with the deployed artifact — no separate storage needed.

Validate

izi validate <file.izi.md>          # diagnostics + artifact kind
izi validate <file.izi.md> --json   # compiled RunSpec IR + diagnostics as JSON

LLM assist

Attach an LLM to the compiler — it explains diagnostics, proposes corrected .izi.md files, and answers questions about the compile targets (which evolve faster than any CLI release):

izi config set llm-provider anthropic     # anthropic (default) | openai | kimi | custom
izi config set llm-api-key sk-...         # or use ANTHROPIC_API_KEY / OPENAI_API_KEY / MOONSHOT_API_KEY

izi compile broken.izi.md --assist        # diagnostics + an LLM explanation & proposed fix
izi validate broken.izi.md --assist
izi assist agent.izi.md "How would %memory map to Mastra's Memory API?"
izi assist agent.izi.md --web             # Claude searches current framework docs (anthropic only)

Config keys (izi config set <key> <value>, env overrides in parentheses):

| Key | Default | Notes | |---|---|---| | llm-provider | anthropic | anthropic, openai, kimi (Moonshot), or custom (IZI_LLM_PROVIDER) | | llm-model | per provider | claude-opus-5 / gpt-5-mini / kimi-latest (IZI_LLM_MODEL) | | llm-api-key | — | falls back to the provider's env var (ANTHROPIC_API_KEY, OPENAI_API_KEY, MOONSHOT_API_KEY, IZI_LLM_API_KEY) | | llm-base-url | per provider | any OpenAI-compatible endpoint for custom (IZI_LLM_BASE_URL) |

The Anthropic provider uses the official SDK (env/ant auth login credentials work with no config at all) and supports --web live search; the others speak the OpenAI-compatible chat/completions protocol, so any conforming endpoint works via custom + llm-base-url.

Example

examples/agent-prospection.izi.md:

@agent('Prospection Agent', 'anthropic/claude-sonnet-4.6')
You are a B2B prospection assistant for the sales team.
Research prospects, qualify them against our ICP, and draft
personalized outreach. Never send anything without approval.

@use('skill:cpaka/qualify-lead')
You may also use %web_fetch and %email.

@config
memory: on
budget: { steps: 40, minutes: 20 }
permissions: ask
@endconfig
@endagent

izi compile examples/agent-prospection.izi.md --mastra
# ✔ Prospection Agent (agent) → examples/agent-prospection.mastra.ts
#   tools: %web_fetch, %email · refs: skill:cpaka/qualify-lead

Registry commands (gitizi.com)

The CLI also syncs artifacts with the gitizi.com registry: izi auth, izi search, izi create, izi push, izi clone, izi list, izi whoami, izi logout. These are optional — the language commands above work fully offline.

Development

npm install
npm run dev -- compile examples/weekly-digest.izi.md --js
npm test
npm run build

The spec-compliant compiler core lives in src/lib/izi/ (parser → RunSpec IR); code generators live in src/emitters/ — adding a new language or framework target means implementing one Emitter and registering it in src/emitters/index.ts.

License

MIT