# Quickstart

URL: https://docs.hanzo.ai/docs/quickstart

> Install the CLI, log in, and make your first call — then see that same call as an SDK method, raw HTTP and an MCP tool.

**After this page you have a working credential and one call that answered.**

Hanzo is one cloud behind one key. Every capability — inference, identity,
storage, money, agents — answers at `https://api.hanzo.ai`, and the CLI, the
SDKs and the MCP tools are all generated from the same description of it. So
there is nothing to wire up per service: get a key once and everything is
reachable.

## Install

**Script**

```bash
curl -fsSL https://hanzo.sh | sh
```

Native binaries, checksummed, into `~/.local/bin`: the CLI, the MCP server, Hanzo Dev and ZT. `https://hanzo.sh/cli` installs the CLI alone, and `hanzo upgrade` keeps them current.

**npm**

```bash
npm i -g hanzo
```

`hanzo` is the CLI and the client in one install.

**Homebrew**

```bash
brew install hanzoai/tap/hanzo
```

**From source**

```bash
git clone https://github.com/hanzoai/cli && cd cli && cargo install --path .
```

```bash
hanzo version
```

## Log in

```bash
hanzo auth login
```

That opens a browser against [hanzo.id](https://hanzo.id), Hanzo's identity
provider, and stores the resulting credential locally. `hanzo auth show` prints
who you are; `hanzo auth list` shows every identity on this machine and
`hanzo auth use` switches between them.

For a server, mint a key instead of logging a person in: **platform.hanzo.ai →
API keys**. A secret key resolves to _you_, so it belongs on a server and never
in a browser — [Authentication](https://docs.hanzo.ai/docs/api-keys) is the whole rule.

```bash
export HANZO_API_KEY=sk-...
```

## List the models

The catalogue of models the gateway currently serves. It needs no key at all,
and it is the same operation on all four surfaces. An `id` from it is what a
request names as `model`.

**CLI**

```bash
hanzo models list
```

**SDK**

**.ts**

```bash
npm i hanzoai
```

```typescript
import { AiApi, Configuration } from 'hanzoai'

const ai = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }))
const { data } = await ai.getModels()
```

**.py**

```bash
pip install "hanzoai>=8"   # Python 3.12 or newer
```

```python
import os
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
models = AiApi(client).get_models()
```

**.go**

```bash
go get github.com/hanzoai/go-sdk/v8
```

```go
import hanzoai "github.com/hanzoai/go-sdk/v8"

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

models, _, err := client.AiAPI.GetModels(context.Background()).Execute()
```

**.rs**

```bash
cargo add hanzo-client
```

```rust
use hanzo_client::apis::{ai_api, configuration::Configuration};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let models = ai_api::get_models(&cfg).await?;
```

Each client is generated from the same description of the API, so the class and
the method both follow from the operation rather than from a hand-written
wrapper — and each carries every `/v1` capability, not just this one. The client
is regenerated per language on its own release schedule, so a method name here
can be a release behind the one the [reference](https://docs.hanzo.ai/docs/openapi) prints; the
reference says so on the operation when it is. [Java, Kotlin, Swift and
C++](https://docs.hanzo.ai/docs/sdks) are at earlier stages — that page says exactly which are on a
registry today.

**HTTP**

```bash
curl https://api.hanzo.ai/v1/models \
  -H "Authorization: Bearer $HANZO_API_KEY"
```

**MCP**

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

One endpoint, one tool per capability. `tools/call` names the capability and the
operation; `describe` explains any operation's input.

Those are one API seen from four places, and the tabs above are the whole
difference. Pick the one you will write in:

- **[CLI](https://docs.hanzo.ai/docs/cli)** — every capability as a command group, one page each.
- **[SDKs](https://docs.hanzo.ai/docs/sdks)** — TypeScript, Python, Go and Rust on a registry today;
  Java, Kotlin, Swift and C++ behind them. Generated from the same description
  the CLI and the tools are.
- **[MCP](https://docs.hanzo.ai/docs/mcp)** — one endpoint an agent connects to; [the tools](https://docs.hanzo.ai/docs/mcp-tools)
  are listed one per capability.

HTTP needs no page: it is `https://api.hanzo.ai` and the key you just exported.

## Send a completion

This is the first step that draws down credit; everything above is free to run.
`zen5` is an `id` the catalogue lists.

**CLI**

```bash
hanzo chat completions --data '{"model":"zen5","messages":[{"role":"user","content":"hello"}]}'
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"zen5","messages":[{"role":"user","content":"hello"}]}'
```

A `401` names what was missing and where a key comes from; a `402
    insufficient_balance` means the key is fine and the org has no credit — see
[Credits & billing](https://docs.hanzo.ai/docs/credits). A `429` carries `Retry-After`, in seconds.

Then read what it drew down:

```bash
hanzo billing balance
hanzo usage summary
```

[Credits & billing](https://docs.hanzo.ai/docs/credits) explains what a credit is and what happens at
zero; [Pricing](https://docs.hanzo.ai/docs/pricing) is the rate for every model and tool.

## Record a fact and read it back

The graph holds what is true of your org's entities, and who said so. Assert
one fact, then resolve what holds now.

```bash
curl -X POST https://api.hanzo.ai/v1/graph \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assertions":[{"entity":"acme","relation":"owner","value":"ada","at":"2026-01-01T00:00:00Z","source":"quickstart"}]}'

curl -X POST https://api.hanzo.ai/v1/graph/resolve \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity":"acme","relation":"owner"}'
```

The assert answers `{"recorded":1,…}`; the resolve answers `"known":true` with
the assertion as `winner`. [Graph](https://docs.hanzo.ai/docs/openapi/graph) is the rest of it.

## Run the cloud locally

The same binary that serves `api.hanzo.ai` runs on your machine:

```bash
hanzo host serve
```

`cloud` is the default, so that is the whole API. Name one service to run it
alone: `hanzo host serve iam`, and likewise `kms`, `gateway`, `storage`,
`pubsub`. `hanzo host start` runs the same thing in the background, with
`status` and `stop` beside it.

`hanzo up` is a different command — it boots k3s in a microVM and hands you a
kubeconfig, which is what you want to run your own _cluster_ rather than your
own cloud. See [Run your own](https://docs.hanzo.ai/docs/network) for what each needs.

## Where to go next

- **[Coding agents](https://docs.hanzo.ai/docs/guides/coding)** — `hanzo --claude`, `--codex`,
  `--gemini` and ten more, with Enso and Kai a tool call away and a summary of
  what each session handed off.
- **[Six flows, four surfaces](https://docs.hanzo.ai/docs/guides)** — hello, chat, money, store, agent,
  tools. The whole product in miniature, each journey shown four ways.
- **[Concepts](https://docs.hanzo.ai/docs/concepts)** — orgs, projects, sandboxes, agents, memory and
  workflows. Read these once and the rest of the API explains itself.
- **[Capabilities](https://docs.hanzo.ai/docs/openapi)** — all of them, grouped. Each page says what
  the capability is, how to reach it from all four surfaces, and links its
  specification.

## When something does not answer

The CLI describes itself, so the fastest answer is usually local:

```bash
hanzo --help              # every capability as a command group
hanzo billing --help      # and every command inside one
```

Support is a capability like any other, which means you can reach it from the
same key you just exported — `hanzo help articles list` reads the knowledge
base, `hanzo help tickets` opens a ticket, and both are `/v1/help` if you would
rather call them over HTTP. [Errors](https://docs.hanzo.ai/docs/errors) explains what a status code
from `api.hanzo.ai` means before you open one.