CLI

martha is the command-line surface for the platform — manage agents, functions, workflows, documents, tasks, integrations, and more. It's also the surface external agent runtimes (Claude Code, CrewAI, Pydantic AI, ork) operate the platform through.

Every command supports JSON output (--json) and predictable exit codes. The full command list shows up under martha --help; this page is the operational reference grouped by what you're trying to do.

Install

The CLI is published on npm as @aiaiai-pt/martha-cli.

bash

# Run on demand (no install)
npx -y @aiaiai-pt/martha-cli@latest --help

# Install globally
npm i -g @aiaiai-pt/martha-cli
martha --version

Pin a version when calling from CI or agent runtimes:

bash

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

Requires Node.js 22+.

Source build (contributors only)

bash

git clone https://github.com/westeuropeco/martha
cd martha/martha-cli
bun install && bun run build
node dist/index.js --help

Set up

`martha init` — first-run wizard

Writes a profile to ~/.martha/config.yaml so you don't have to learn the YAML schema. Two presets:

bash

martha init                          # interactive, defaults to cloud preset
martha init --preset cloud           # martha.nomadriver.co + auth.nomadriver.co
martha init --preset local           # http://localhost:8080 + 8180
martha init --no-interactive --name staging --api-url https://staging.example.com

`martha doctor` — diagnostic

Checks API reachability, Keycloak reachability, token validity, and CLI/API version skew. Run this first when something feels off.

bash

martha doctor

Exits non-zero only on hard failures. Soft warnings (no token stored, etc.) don't fail the check.

`martha skill` — print agent skill bundle

Prints the bundled SKILL.md reference to stdout for agent runtimes. Pipe a head into the agent's prompt context:

bash

npx -y @aiaiai-pt/martha-cli@latest skill | head -200

`martha status` — quick health snapshot

bash

martha status

Profile name, API URL, auth state, and a live API health ping in one place.

Authenticate

bash

# Browser PKCE flow (humans, local dev)
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

# Bypass auth entirely with a pre-issued token
export MARTHA_TOKEN="eyJhbGc..."

# Inspect, get, or clear
martha auth status
martha auth token        # raw JWT to stdout (for piping into curl)
martha auth logout

Service-account tokens auto-refresh ~30 s before expiry. Human tokens expire after ~5 min and require re-login (or the MARTHA_TOKEN env var for long-running scripts).

Definitions: agents, functions, workflows

The three definition types share the same CRUD surface.

CRUD

bash

# List
martha agents list
martha functions list --inactive
martha workflows list --json

# Get details
martha agents get support-bot
martha functions get search_documents

# Create from a YAML/JSON file
martha agents create -f support-bot.yaml

# Update
martha functions update search_documents -f search.yaml

# Delete (soft by default; --hard for permanent)
martha agents delete old-bot
martha workflows delete old-pipeline --hard --yes

# Version history + rollback
martha functions versions search_documents
martha functions rollback search_documents 2

Declarative apply

definitions apply reads YAML/JSON files, compares against remote state, and creates or updates. It never deletes — making it safe to run from CI on every push.

bash

martha definitions apply -f support-bot.yaml
martha definitions apply -f definitions/                # whole directory
martha definitions apply -f all.yaml                    # multi-doc YAML
martha definitions apply -f definitions/ --dry-run      # preview only
martha definitions apply -f definitions/ --yes --json   # CI mode

File format

Each definition needs kind and name. Other fields are kind-specific.

yaml

kind: Function
name: search_documents
description: Search across document collections
endpoint: https://api.example.com/search
http_method: POST
parameters:
  - { name: query, type: string, required: true }
---
kind: Agent
name: support-bot
description: Customer support agent
system_prompt: You are a helpful assistant.

Valid kinds: Function, Workflow, Agent.

Behavior

Local vs remote	Action
Doesn't exist remotely	Create
Content differs	Update (new version)
Content matches	Skip
Exists remotely but not locally	Untouched (never deletes)

Export

bash

martha definitions export -o ./definitions/
martha definitions export --kind Agent -o ./agents/
martha definitions export --json --kind Function > functions.json

Workflow execution

bash

martha workflows execute my-pipeline --inputs '{"key": "value"}'
martha workflows execute my-pipeline --follow                # stream output
martha workflows execution <execution-id>
martha workflows execution <execution-id> --follow
martha workflows executions --status running
martha workflows cancel <execution-id>
martha workflows inputs my-pipeline                          # show expected schema

Workflow introspection

bash

martha workflows nodes my-pipeline                  # list nodes + connections
martha workflows node-types                         # all available types
martha workflows node-type llm                      # config schema for a type

Chat

bash

# Interactive chat REPL
martha chat
martha chat --client my-bot

# One-shot
martha chat --message "Summarise my open tasks."
martha chat --client my-bot --message "Hello" --json

Without --client, the tenant's default client is used.

Sessions

bash

martha sessions list                                # recent chat sessions
martha sessions list --client my-bot --status active
martha sessions get <session-id>                    # session detail + messages
martha sessions messages <session-id> --limit 50    # message history
martha sessions delete <session-id> --yes

Documents

bash

martha documents collections                                       # list collections
martha documents create-collection --name kb --description "..."
martha documents list --collection kb
martha documents upload ./report.pdf --collection kb
martha documents upload ./policies/ --collection kb --recursive    # whole folder
martha documents get <document-id>
martha documents revisions <document-id>                           # version history
martha documents reingest <document-id>                            # rerun the pipeline
martha documents delete <document-id> --yes

Uploads kick off the parse → chunk → embed pipeline automatically. See Document ingestion for what each stage does.

Wiki

The wiki is the tenant-level compiled knowledge base distilled from your documents.

bash

martha wiki list                                    # list wiki pages
martha wiki get topics/installation/chimney         # show one page (markdown)
martha wiki search "antenna mounting"               # full-text + semantic search
martha wiki settings get                            # current caps + policies
martha wiki settings set --max-pages-per-source 5
martha wiki schema get                              # tenant-defined schema markdown
martha wiki schema set -f schema.md                 # update schema
martha wiki recompile                               # re-run compile from current docs

Tasks

Async work queue for agents to claim and complete.

bash

martha tasks list                                              # all open tasks
martha tasks list --status open --priority high
martha tasks list --tracker linear                             # filter by tracker
martha tasks create --goal "Investigate latency regression" --priority high
martha tasks get <task-id>
martha tasks claim <task-id>                                   # mark claimed
martha tasks heartbeat <task-id>                               # stay alive
martha tasks complete <task-id> --result "Root cause: …"
martha tasks fail <task-id> --error "Couldn't reproduce"
martha tasks cancel <task-id>

Tasks can carry an external_ref linking them to Linear/GitHub/GitLab issues for bidirectional sync.

Teams

bash

martha teams list
martha teams create --name code-review --strategy round_robin
martha teams add-agent code-review reviewer-1
martha teams add-agent code-review reviewer-2
martha teams remove-agent code-review reviewer-1
martha teams delete code-review --yes

Strategies: round_robin, manual, external.

Approvals

bash

martha approvals list                                # all pending
martha approvals list --status pending --requester support-bot
martha approvals get <approval-id>
martha approvals approve <approval-id> --reason "Verified with customer"
martha approvals reject <approval-id> --reason "Out of scope"

Models

bash

martha models list                                   # available models
martha models list --provider anthropic
martha models default                                # current default
martha models default --set claude-sonnet-4-6        # set tenant default

Clients

A Client is a consumer of your agents (chat web app, SMS sender, voice line, embedded widget). Each has its own credentials and per-feature allowlists.

bash

martha clients list
martha clients create --name my-bot
martha clients update my-bot --default               # set as tenant default
martha clients grant my-bot function search_documents
martha clients grant my-bot workflow data_pipeline
martha clients grant my-bot agent support-bot
martha clients revoke my-bot function search_documents
martha clients access my-bot                         # show all grants
martha clients delete my-bot --yes

Embed key management

For embeddable chat clients, manage the credential the front-end uses to mint short-lived tokens server-side:

bash

martha clients embed urls                            # current hosted widget URLs
martha clients embed key rotate my-bot               # rotate the embed token signing key
martha clients embed key clear my-bot                # disable embed for this client

Integrations

bash

# Overview
martha integrations list                             # core / plugin / connected / custom
martha integrations specs                            # OpenAPI specs in the tenant

# Import an external API
martha integrations import-openapi \
  --source https://api.example.com/openapi.json \
  --name my-api
martha integrations sync <spec-id>                   # re-sync a previously imported spec

# Plugins (first-party services with manifests)
martha integrations plugins
martha integrations plugin martha-scoring             # full detail
martha integrations proxy martha-scoring GET /health
martha integrations proxy martha-scoring POST /score --data '{"item_id":"123"}'
martha integrations proxy martha-scoring GET /rubrics --query "limit=10"

The proxy injects tenant context automatically — no auth wiring required.

Notifications

Pre-configured notification channels (email, Slack, HTTP webhooks) callable from workflow nodes.

bash

martha notifications channels                       # list available channels
martha notifications connections list               # tenant connections
martha notifications connections create \
  --provider slack \
  --name eng-alerts \
  --config '{"webhook_url":"https://hooks.slack.com/..."}'
martha notifications connections delete eng-alerts --yes
martha notifications send --channel email --to "..." --subject "..." --body "..."

See Notification channels for full schema and routing.

Messaging

Manage messaging-channel adapters (SMS / WhatsApp via your provider).

bash

martha messaging providers                          # configured providers
martha messaging numbers                            # active numbers
martha messaging numbers add --number +351... --provider infobip
martha messaging numbers test +351... --message "Test"

Configuration

bash

martha config init                                   # initial setup wizard
martha config show                                   # current config
martha config set api_url https://api.example.com
martha config profiles                               # list profiles
martha config use staging                            # switch active profile

Global flags

Flag	What it does
`--profile <name>`	Use a named profile from `~/.martha/config.yaml`
`--json`	Machine-readable JSON on stdout. Always set when piping to `jq` or parsing in scripts.
`--api-url <url>`	Override the API URL for this invocation
`--verbose`	DEBUG-level logging on stderr (HTTP requests, retry attempts, token refresh)
`--quiet`	Suppress informational output. Errors still print.
`--no-color`	Disable colored output
`--yes`	Skip confirmation prompts. Required in non-TTY contexts (CI, agents) — the CLI does not silently cancel without it.
`--version`	Print the CLI version

Exit codes

Code	Meaning
0	Success
1	Generic error
2	Auth failure (token missing, expired, or rejected)
3	Not found (404)
4	Validation error (400 / 422)
5	Conflict (409)

Agent integration — using the CLI from external LLM-agent harnesses
Composable workflows — what to put inside a workflow YAML
OpenAPI integrations — wrapping external APIs as agent tools

CLI ​

Install ​

Source build (contributors only) ​

Set up ​

martha init — first-run wizard ​

martha doctor — diagnostic ​

martha skill — print agent skill bundle ​

martha status — quick health snapshot ​

Authenticate ​

Definitions: agents, functions, workflows ​

CRUD ​

Declarative apply ​

File format ​

Behavior ​

Export ​

Workflow execution ​

Workflow introspection ​

Chat ​

Sessions ​

Documents ​

Wiki ​

Tasks ​

Teams ​

Approvals ​

Models ​

Clients ​

Embed key management ​

Integrations ​

Notifications ​

Messaging ​

Configuration ​

Global flags ​

Exit codes ​

More ​

CLI

Install

Source build (contributors only)

Set up

`martha init` — first-run wizard

`martha doctor` — diagnostic

`martha skill` — print agent skill bundle

`martha status` — quick health snapshot

Authenticate

Definitions: agents, functions, workflows

CRUD

Declarative apply

File format

Behavior

Export

Workflow execution

Workflow introspection

Chat

Sessions

Documents

Wiki

Tasks

Teams

Approvals

Models

Clients

Embed key management

Integrations

Notifications

Messaging

Configuration

Global flags

Exit codes

More