# izi > The IZI language CLI — compile .izi.md AI artifacts (prompts, workflows, agents, skills) to deployable code (JS, Python, Mastra), decompile them back, and validate against IZI_SPEC v1.0. Latest version **5.0.0** (published 2026-08-02) · MIT license · 0 weekly downloads ## Install ```sh npm install izi pnpm add izi yarn add izi bun add izi ``` Provides the command `izi`. ## Health **Score 65/100 (B)** — status: active. Positive: has types; no vulnerabilities; recently updated; high maintenance score; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 5.0.0 | | Published | 2026-08-02 | | First published | 2016-05-19 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=14.0.0 | | Dependencies | 10 | | Unpacked size | 459.6 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Author | Gitizi | | Maintainers | gitizi | | Keywords | izi, izi-lang, ai-orchestration, compiler, agents, workflows, skills, prompts, llm, mastra, anthropic, cli, gitizi | ## Links - npm: https://www.npmjs.com/package/izi - Repository: https://github.com/Gitizihq/izi - Homepage: https://gitizi.com - Issues: https://github.com/Gitizihq/izi/issues - npm.io page: https://npm.io/package/izi ## Dependencies (10) - [ora](https://npm.io/package/ora.md) ^5.4.1 - [conf](https://npm.io/package/conf.md) ^10.2.0 - [axios](https://npm.io/package/axios.md) ^1.12.2 - [chalk](https://npm.io/package/chalk.md) ^4.1.2 - [inquirer](https://npm.io/package/inquirer.md) ^12.10.0 - [commander](https://npm.io/package/commander.md) ^14.0.2 - [axios-retry](https://npm.io/package/axios-retry.md) ^4.5.0 - [gray-matter](https://npm.io/package/gray-matter.md) ^4.0.3 - [@anthropic-ai/sdk](https://npm.io/package/@anthropic-ai/sdk.md) ^0.115.0 - [@supabase/supabase-js](https://npm.io/package/@supabase/supabase-js.md) ^2.76.1 ## Alternatives - [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads - [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads - [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads - [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads - [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads ## Recent versions - 5.0.0 (latest) — 2026-08-02 - 4.0.0 — 2025-11-01 - 3.1.0 — 2017-05-21 - 3.0.1 — 2017-05-08 - 2.1.0 — 2017-04-25 - 3.0.0 — 2017-04-15 - 2.0.1 — 2017-02-18 - 2.0.0 — 2017-02-18 - 1.0.4 — 2016-08-17 - 1.0.4-1 — 2016-08-17 - 1.0.4-0 — 2016-08-17 - 1.0.3-0 — 2016-08-12 - 1.0.2 — 2016-08-12 - 1.0.1 — 2016-07-29 - 1.0.1-19 — 2016-07-28 - … 20 more at https://npm.io/package/izi/versions ## README # 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. ```bash 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 ```bash npm install -g izi # or npx izi ``` ## Compile ```bash izi compile [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 ` (explicit form), `-o, --out `, `--ir ` (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 ```bash izi decompile [-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 ```bash izi validate # diagnostics + artifact kind izi validate --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): ```bash 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 `, 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`: ```markdown @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 ``` ```bash 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](https://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 ```bash 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 --- _Source: https://npm.io/package/izi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._