Quickstart

This guide takes you from nothing installed to your first governed API call. Every step shows expected output so you can verify progress. Budget: under ten minutes.

Prerequisites: Node.js 20+ (22 recommended) and a HUMΛN account — create one in the Console if you don't have one yet.

1. Install the CLI

npm install -g @human/cli
human --version

Expected output:

1.0.0

2. Authenticate

human login

The CLI opens a device-flow login. When it completes:

✔ Authenticated as did:human:…
  Profile saved to ~/.human/config.yaml

Working against a self-hosted or local stack instead? Point your profile at it first: human config set profiles.default.apiUrl http://localhost:3001. Everything below works the same.

3. Verify your identity

human whoami
human doctor

whoami prints your Passport DID, active profile, and token status. doctor runs a full environment health check — the lines that matter (abridged; you may also see warnings for optional features, which is normal):

✅ Node.js Version: v22.14.0 (compatible)
✅ Config file: ~/.human/config.yaml
✅ Delegation token: Token accepted by API
✅ API Connectivity: Connected to https://api.haio.run

That DID is your Passport — the identity every call you make is attributed to.

4. Make your first governed call

Every API call runs under a delegation — a scoped grant that says what the caller may do. Grab a delegation token from the Console (Settings → API tokens) or use the one human login stored, then:

export HUMAN_DELEGATION_TOKEN="<your token>"

curl -s -H "Authorization: Bearer $HUMAN_DELEGATION_TOKEN" \
  "https://api.haio.run/v1/agents" | head -c 400

Expected shape:

{"data":[],"has_more":false,"next_cursor":null}

An empty list on a fresh account is correct — the point is what just happened: the call was authenticated against your Passport, checked against your delegation's scopes, and recorded with signed provenance. You did not build any of that.

5. The same call from the SDK

~~~multi-lang typescript:TypeScript

import { HumanClient } from '@human/sdk';

const client = new HumanClient({
  baseUrl: 'https://api.haio.run',
  delegationToken: process.env.HUMAN_DELEGATION_TOKEN!,
});

const { data, error } = await client.raw.GET('/v1/agents');
if (error) throw error;
console.log(`${data.data.length} agents`);

python:Python

import asyncio
import os

from human_sdk import HumanClient


async def main() -> None:
    async with HumanClient(
        delegation_token=os.environ["HUMAN_DELEGATION_TOKEN"],
    ) as client:
        page = await client.agents().list()
        print(f"{len(page['data'])} agents")


asyncio.run(main())

go:Go

package main

import (
	"context"
	"fmt"
	"os"

	humansdk "github.com/rkbush/human/packages/sdk-go"
)

func main() {
	client, err := humansdk.NewHumanClient(os.Getenv("HUMAN_DELEGATION_TOKEN"))
	if err != nil {
		panic(err)
	}
	agents, err := client.Agents().List(context.Background(), nil)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%d agents\n", len(agents))
}

rust:Rust

use human_sdk::HumanClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HumanClient::builder()
        .delegation_token(std::env::var("HUMAN_DELEGATION_TOKEN")?)
        .build()?;
    let agents = client.agents().list().await?;
    println!("{} agents", agents.len());
    Ok(())
}

cli:CLI

human cp agents list
# or raw:
human api GET /v1/agents

bash:cURL

curl -s https://api.haio.run/v1/agents \
  -H "Authorization: Bearer $HUMAN_DELEGATION_TOKEN"

~~~

6. Scaffold something real

mkdir human-demo && cd human-demo
human connector create my-crm --marketplace

Expected output:

✅ Created my-crm-connector/ (marketplace BaseConnector)

The scaffold is a complete connector project — handler, manifest, tests, and icon. From here the loop is: edit src/index.ts, run npm test, validate with human marketplace dev test, and human marketplace publish when it's ready to share.

Where to go next

You have a working identity, a governed call, and a scaffolded project. Two paths from here:

Keep building — build your first extension takes the scaffold all the way to a governed workflow in the Console, and the pattern library has working recipes for the tasks in between.

Understand what just happened — the core concepts ladder explains the Passport, delegation, and provenance machinery your call ran through.