martha-cli

Terminal-first client for the Martha AI platform.

Manage agents, functions, workflows, tasks, documents, and more from your shell. Designed for both human developers and external agent harnesses (Claude Code, ork, CrewAI, Pydantic AI, etc.) — see Agent integration below.

Install

Run on demand (recommended)

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

Pin a version when calling from CI or agent runtimes:

npx -y @aiaiai-pt/[email protected] agents list --json

Install globally

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

Requires Node.js >= 22.

Quickstart

# 1. Configure a profile — writes ~/.martha/config.yaml
martha init                       # interactive (defaults to cloud preset)
martha init --preset local        # localhost dev stack
martha init --no-interactive --name staging --api-url https://...   # scripted

# 2. Authenticate
martha auth login                 # browser flow (PKCE)
martha auth login --username u --password p   # headless
export MARTHA_TOKEN=eyJhbGc...    # bypass login (CI / one-off)

# 3. Verify everything is wired up
martha doctor                     # API + Keycloak + token + version skew

# 4. Run something
martha agents list
martha functions list --json | jq '.[].name'
martha chat my-agent "Summarise the latest task in tracker INGEST-42"

Full command reference: martha --help (or any subcommand --help).

Configuration

Profiles live at ~/.martha/config.yaml. Each profile defines:

current_profile: default
profiles:
  default:
    api_url: https://martha.nomadriver.co
    keycloak_url: https://auth.nomadriver.co
    keycloak_realm: frank
    auth_type: oidc

Override per-command:

martha --profile staging agents list
martha --api-url http://localhost:8080 status
MARTHA_PROFILE=cloud martha tasks list

Auth precedence

1. MARTHA_TOKEN env var (raw JWT, bypasses everything)
2. MARTHA_CLIENT_ID + MARTHA_CLIENT_SECRET (client_credentials grant, auto-refresh)
3. Profile-stored token from prior martha auth login
4. Browser-based OIDC (interactive only)

JSON output

Every command supports --json for machine-readable output. Use it when piping to jq or calling from scripts/agents:

martha agents list --json | jq '.[] | {name, status}'

Exit codes: 0 success · 1 generic error · 2 auth failure · 3 not found · 4 validation · 5 conflict (409).

Put an agent in a Buzz channel

One command, no install of its own:

npx -y @aiaiai-pt/martha-cli channels install-harness buzz

Then in Buzz Desktop: New agent → runtime "Martha". The command registers Martha as an ACP runtime by writing a definition into Buzz's own app-data directory — the supported route for any ACP agent, no PR and no plugin.

To have an agent for it to be, and leave Buzz's Edit Agent empty:

martha principals bootstrap --mode agent --agent support \
  --prompt "You answer support questions from our handbook." \
  --intents rag --collections "Handbook" --save-profile support
martha channels install-harness buzz --use-profile support

The profile name goes in the definition; the credential stays in ~/.martha/credentials.json (0600). Check everything before trusting it with martha channels preflight buzz --agent support --relay wss://…, which names each missing precondition and exits non-zero. Full guide: https://docs.martha.nomadriver.co/buzz.

Agent integration

This package ships an agent-facing skill reference at skills/martha-cli/SKILL.md describing every command, JSON contract, and conceptual primitive (tenant, agent, function, task, etc.). Agent harnesses can pull it directly:

# Print the skill to stdout (works for npm i -g and npx)
martha skill

# Seed an agent's prompt context
npx -y @aiaiai-pt/martha-cli@latest skill | head -200

Stability

0.x releases may change CLI flags or JSON output between minor versions. Pin a version in CI/agent contexts:

npx -y @aiaiai-pt/[email protected] ...

1.0.0 will commit to a stable contract — see the tracking issue.

Development

cd martha-cli
bun install
bun run dev -- agents list      # run from source
bun run build                   # produce dist/index.js
bun run test:run                # unit + integration tests
MARTHA_LIVE=1 bun run test:run tests/live/  # live tests against local Martha

The CLI lives in the westeuropeco/martha monorepo under martha-cli/. PRs welcome.

License

MIT