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 --package=@aiaiai-pt/martha-cli@latest martha --help

For day-to-day use, install globally:

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

2. Configure a profile

martha init

Install does not create a profile. The interactive wizard writes ~/.martha/config.yaml with a local profile by default. To skip the prompts for local development:

martha init --no-interactive --preset local

For a customer, staging, or private-cloud tenant, use the URLs from your tenant admin:

martha init --no-interactive --name acme \
  --api-url https://martha.acme.example \
  --keycloak-url https://auth.acme.example \
  --keycloak-realm acme

The hosted Martha cloud profile is explicit and uses martha.nomadriver.co plus the verified Frank Keycloak issuer:

martha init --preset cloud

Bootstrap access in the same step

Run interactively and martha init does more than write a profile: after the URL prompts it offers to provision a grant-bearing principal so your first call just works — no waiting on an admin to hand-grant functions.

$ martha init
  ...URL prompts...
  Provision an access principal now so calls just work? [Y/n] y
  How will you run Martha?
    1) This machine (you)
    2) An integration / CI (service account)
  Choose [1] 1
  How will you use Martha? (comma-separated)
    1) rag — retrieve from collections (query, search, read)
    2) documents — browse + fetch documents
    3) workflows — execute workflows (grants the workflows + the rag read set)
    4) custom — pick exact functions / workflows yourself
  Select [1] 1
  Opening browser for login...
  Created client CLI · you · a1b2c3d4 (#42).
    Granted functions: query_collection, search_docs, read_doc, list_docs, list_collections, visual_search
    Profile cloud will now run as this client.

It logs you in (browser PKCE) if needed, creates a Client scoped to you (not the shared tenant default), grants exactly the read set for your declared intent, and wires the profile to run as that client. Re-running adopts the same principal instead of duplicating it.

You can skip the prompts — useful for scripted setup and CI:

# Provision your own access non-interactively (must already be authenticated)
martha init --bootstrap --mode human --intent rag --yes

# Mint a service account for CI (admin only) — prints credentials once
martha init --bootstrap --mode integration --intent rag --label ci-rag --yes

The integration form prints copy-paste MARTHA_CLIENT_ID / MARTHA_CLIENT_SECRET exactly once — store them in your CI secrets, then authenticate with martha auth login --service-account. See the CLI guide for the full intent → grant table.

Add --agent to also provision a chat copilot you can talk to — martha init --bootstrap --intent rag --agent then martha chat "what can you do?". See Chat copilot.

If you'd rather authenticate manually and grant access separately, skip the bootstrap and use the steps below.

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 [email protected] --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 --client my-bot --message "Summarize what you can do."

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

Tenant onboarding

Martha is invite-only today — public self-serve sign-up isn't open yet. To get a tenant:

1. Reach out to your contact at aiaiai-pt.
2. They'll provision your tenant and hand you two credentials:
   • A client ID + client secret for service accounts and agent runtimes (machine-to-machine, no browser).
   • An email + temporary password for browser PKCE login.
3. Use either set with martha auth login per the modes above.

Public sign-up opens 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