> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mzizi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# The CLI

> @nyuchi/mzizi-cli: the mzizi add installer, Rust first, and the fundi commands that explore a project and plan wiring Mzizi in. Free, with no gate.

<Note>
  This is the CLI for working with Mzizi's **components and doctrine** in a project. The
  language's own command-line tool is `mz`; see [the compiler](/compiler).
</Note>

The CLI is **free, with no gate**. That is the owner's decision of 29 September 2026: gating
starts only at Fundi, which ties into the console.

## Install

```bash theme={null}
pnpm add -D @nyuchi/mzizi-cli
```

The package is [`@nyuchi/mzizi-cli`](https://www.npmjs.com/package/@nyuchi/mzizi-cli). It
installs two names for the same program, `mzizi` and `fundi`. The latest published version
is `0.6.3`, read from npm on 30 September 2026. It needs Node 20 or later.

<Warning>
  **Use `0.6.1` or later, not `0.6.0`.** In `0.6.0` both binaries printed nothing and exited
  `0`, because the entry-point check compared a symlinked path with the resolved file.
  `0.6.1` fixes it.
</Warning>

What changed since `0.6.1`:

| Version | Change |
| - | - |
| `0.6.2` | The request the CLI makes to crates.io names the project's support address, `support@bundu.org`, in its `User-Agent`. Earlier versions sent a person's own address there |
| `0.6.3` | Depends on `@nyuchi/mzizi-skills` `^0.8.0`, so the CLI bundles [the five current skills](/toolchain/skills) rather than the `0.7.x` set |

## Commands

| Command | What it does |
| - | - |
| `mzizi add <name...>` | Installs components from the registry, with their dependencies. Rust first. No API key and no sign-in |
| `fundi explore` | Reads a few files (`package.json`, `tsconfig.json`, the global stylesheet, the Tailwind config, `components.json`) and prints a project snapshot. Offline. No model call |
| `fundi plan <goal>` | **Read-only.** Plans the minimal edits to wire Mzizi in, and prints them as a dry run |
| `fundi chat <message>` | One-shot chat scoped to Mzizi doctrine |
| `fundi login` / `logout` / `whoami` | Save, clear or show a console token. Only the gated Fundi tools need one |

Every command works under either name: `fundi add` and `mzizi add` are the same.

## `mzizi add`: the registry installer

```bash theme={null}
mzizi add button --target rust     # the Rust build, explicitly
mzizi add app-data-table --target astro  # the pure Astro build, into src/components/mzizi/
mzizi add button                   # infer the target from the project
mzizi add address-input --dry-run  # print the plan, write nothing
mzizi add card --overwrite         # replace files that already exist
```

It resolves a component and its registry dependencies from `api.mzizi.dev` and needs no
account and no API key. It does not touch the MCP server.

**Rust first.** For a Rust project, `mzizi add` does not copy `.rs` sources in. It names the
crate that holds the component and prints the `cargo add` to run, because the crates are on
crates.io (see [Mzizi Roots](/roots/overview#install)). In a project with only a
`Cargo.toml`:

```text theme={null}
$ mzizi add button
target: rust (Cargo.toml present and no package.json)
…
crate dependency: mzizi-ui (crates.io)

Still to do — add the crate dependency:
  cargo add mzizi-ui
```

The crate name comes from the `crate` field of the API's `/v1/rs/{name}` response, which
names each component's own crate: `mzizi add mzizi-alert-banner` records `mzizi-brand`, and
`mzizi add mzizi-footer` records `mzizi-shell`.
[The Roots crate list](/roots/overview#what-exists-today) says what each crate holds, and
`mzizi-roots` brings the UI crates in one dependency.

For a React project, it writes the `.tsx` files and lists the npm packages they need, as the
shadcn CLI would.

**The target** is inferred from the project, and `--target rust`, `--target tsx` or
`--target astro` overrides it. A project with both a `Cargo.toml` and a `package.json` is
ambiguous, so `mzizi add` refuses and asks for `--target` rather than guess. An Astro project
(even one with React islands) infers `astro` (from `@nyuchi/mzizi-cli` 0.7.0): it installs a
component's pure `.astro` from `api.mzizi.dev/v1/astro/<name>`, with every registry file it
imports and any brand asset, into `src/components/mzizi/`, and refuses by name a component that
has no `.astro` rather than install its `.tsx`.

## Model access

`ANTHROPIC_API_KEY` is optional. Like `tsc`, the CLI is usually run by a coding agent that
already has model access. Without a key, `plan` prints a deterministic context bundle, the
project snapshot plus the Mzizi skills that match your goal, for that agent to plan from, and
`chat` points you back at the agent. With a key, `plan` and `chat` run Fundi's own agent loop.

## Registry access

`plan` and `chat` read the registry through [the MCP server](/toolchain/mcp), which serves
every tool but the Fundi tools without sign-in. So `explore`, `plan`, `chat` and `add` need no
account. `fundi login` exists only for the Fundi tools, which act as a Mzizi console user.

## Safety

* **Planning is read-only.** Writing a file and running a shell command are blocked while
  planning, and reachable only through an explicit non-dry-run apply.
* **Everything is sandboxed to the project root.** A path that escapes it is rejected, in
  planning and in apply.
* **`mzizi add` does not overwrite by default.** A file that already exists is not replaced unless you
  pass `--overwrite`.
* **The CLI never holds a machine credential.** It reaches Fundi only through the MCP server,
  which acts for a signed-in user.

## As a library

```ts theme={null}
import { createFundi } from "@nyuchi/mzizi-cli"

const fundi = await createFundi({
  projectRoot: process.cwd(),
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
})

const snapshot = await fundi.explore()
const plan = await fundi.plan("add the Mzizi token layer and a button", snapshot)
await plan.apply({ dryRun: true })
```

The SDK reads no environment variables itself; the CLI wires them in. As a library,
`createFundi()` still takes a key.

## Two things called fundi

The name appears twice, and they are different things.

<CardGroup cols={2}>
  <Card title="Fundi, the agent behind the console" icon="activity">
    The self-healing agent and issue desk, run under Nyuchi and tied into the console. Its
    architecture counterpart is the N9 fundi rung of [the helix](/architecture/overview).
    It runs as a service, not as something you install.
  </Card>

  <Card title="`fundi`, the CLI binary" icon="terminal">
    The binary in `@nyuchi/mzizi-cli`, described on this page. You install it in your own
    project and it helps you set Mzizi up there. It does not run the self-healing loop.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.