Quickstart

Get from zero to your first Martha API call in under five minutes.

What you need

• Node.js 22+ (for the CLI)
• A Martha tenant — see Tenant onboarding below if you don't have one
• A few minutes

1. Install the CLI

The fastest path is npx — no global install needed:

npx -y @aiaiai-pt/martha-cli@latest --help

For day-to-day use, install globally:

npm i -g @aiaiai-pt/martha-cli
martha --version

2. Configure a profile

martha init

The interactive wizard writes ~/.martha/config.yaml with a cloud profile pointing at martha.nomadriver.co. To skip the prompts:

martha init --no-interactive --preset cloud

For a local-development stack, swap the preset:

martha init --preset local --name local

3. Authenticate

Three modes, depending on what you have:

# Browser PKCE (interactive, for human developers)
martha auth login

# Headless password grant (scripted human login)
martha auth login --username you@example.com --password '...'

# Service account (CI, agent runtimes)
export MARTHA_CLIENT_ID="martha-tenant-acme-client"
export MARTHA_CLIENT_SECRET="..."
martha auth login --service-account

The credentials come from your tenant admin (see below).

4. Verify everything is wired up

martha doctor

You should see five PASS lines (or the API auth check WARN-skipped if you haven't authenticated yet). Anything FAIL will print a specific remedy.

5. Run something

martha agents list
martha functions list --json | jq '.[].name'
martha chat <agent-name> "Summarize what you can do."

Full command surface: martha --help or any subcommand --help.

Tenant onboarding

Martha is currently invite-only — there's no public self-serve signup yet. To get a tenant:

1. Reach out to your contact at aiaiai-pt
2. They'll provision your tenant via the admin UI — this creates a Martha tenant row, a Keycloak confidential client, a tenant group, and a first admin user
3. They'll hand you back two things:
   • A client ID + client secret (for service accounts and agent runtimes)
   • An email + temporary password (for browser PKCE login)
4. Use either with martha auth login per the modes above

Public Keycloak self-registration is on the roadmap once per-tenant rate limits and billing are in place.

What's next

• CLI reference — every command and flag
• Agent integration — using Martha from CrewAI, Pydantic AI, ork, Claude Code
• Embeddable chat — drop the chat widget into your own product