Martha CLI

The Martha CLI (martha) provides command-line access to manage functions, workflows, and agents. It supports both interactive use and CI/CD automation.

Installation

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

# 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 in agent runtimes / CI to avoid silently picking up flag or JSON-contract changes:

npx -y @aiaiai-pt/martha-cli@0.3.0 ...

Requires Node.js 22+.

Source build (contributors only)

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

Authentication

# Interactive login (opens browser for PKCE flow)
martha auth login

# Service account (CI/CD)
martha auth login --client-id my-service --client-secret $SECRET

# Environment variable bypass
export MARTHA_TOKEN="your-jwt-token"

Managing Definitions

CRUD Commands

Each definition type (functions, workflows, agents) supports the same set of subcommands:

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

# Get details
martha functions get search_documents

# Create from file
martha functions create -f search.yaml

# Update
martha functions update search_documents -f search.yaml

# Delete (with confirmation)
martha functions delete old_tool
martha functions delete old_tool --hard --yes

# Version history
martha functions versions search_documents

# Rollback
martha functions rollback search_documents 2

Declarative Apply

The definitions apply command reads YAML/JSON files, compares against remote state, and creates or updates definitions as needed. It never deletes.

# Single file
martha definitions apply -f search.yaml

# Directory of definitions (flat)
martha definitions apply -f definitions/

# Multi-document YAML (--- separators)
martha definitions apply -f all-definitions.yaml

# Preview without applying
martha definitions apply -f definitions/ --dry-run

# Skip confirmation (for CI/CD)
martha definitions apply -f definitions/ --yes

File Format

Each definition requires kind and name. All other fields are type-specific:

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
Exists, content differs	Update (new version)
Exists, content matches	Skip (no-op)
Exists remotely but not locally	Nothing (never deletes)

CI/CD Usage

In non-interactive environments, --yes is required:

# CI pipeline
martha definitions apply -f definitions/ --yes --json

The --json flag outputs machine-readable JSON for all operations, including plan preview and apply results.

!!! warning "Non-interactive mode" Without --yes, the command will fail in non-TTY environments (like CI) with an explicit error rather than silently doing nothing.

Configuration

# Initialize config
martha config init

# Show current config
martha config show

# Set values
martha config set api_url https://api.example.com

# Manage profiles
martha config profiles
martha config use production

Global Flags

Flag	Description
--profile <name>	Use a named configuration profile
--json	Machine-readable JSON output on stdout
--api-url <url>	Override API base URL
--no-color	Disable colored output
--version	Print CLI version

Client Management

Clients represent chat API consumers. Each client can be granted access to specific functions, workflows, and agents.

# List clients
martha clients list

# Create a client
martha clients create --name "my-bot"

# Update a client (set as default)
martha clients update my-bot --default

# Grant access
martha clients grant my-bot function search_documents
martha clients grant my-bot workflow data_pipeline
martha clients grant my-bot agent support-bot

# Revoke access
martha clients revoke my-bot function search_documents

# View all access grants
martha clients access my-bot

# Delete a client
martha clients delete my-bot --yes

Chat with a specific client

# Interactive chat using a specific client's context
martha chat --client my-bot

# One-shot message
martha chat --client my-bot --message "Hello"

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

Workflow Execution

# Execute a workflow
martha workflows execute my-workflow --inputs '{"key": "value"}'

# Follow execution in real-time
martha workflows execute my-workflow --follow

# Check status
martha workflows execution <execution-id>

# Follow a running execution
martha workflows execution <execution-id> --follow

# List executions
martha workflows executions --status running

# Cancel
martha workflows cancel <execution-id>

# Show expected inputs
martha workflows inputs my-workflow

Workflow Introspection

Inspect the structure of workflows and available node types:

# List nodes in a workflow
martha workflows nodes my-workflow
# Output:
# ID            TYPE     LABEL           CONNECTIONS
# start         start    Start           profile_source
# profile_source llm     Profile Source   analyze_gap
# ...

# List all available node types
martha workflows node-types

# Show config schema for a node type
martha workflows node-type llm
# Output:
# LLM Inference (llm)
#   Category:    processing
#   Handler:     activity:execute_llm_node_activity
#   Config Schema:
#     FIELD          TYPE     REQUIRED  DEFAULT
#     model          string   -         "claude-sonnet-4"
#     prompt         string   yes       -
#     ...

Integrations & Plugins

Integration Overview

# List all integrations (core, plugin, connected, custom)
martha integrations list

# List OpenAPI specs
martha integrations specs

# Sync an OpenAPI spec
martha integrations sync <spec-id>

# Import a new OpenAPI spec
martha integrations import-openapi --source https://api.example.com/openapi.json --name my-api

Plugin Inspection

Plugins are first-party services registered with a manifest. The CLI exposes their full API surface:

# List plugins with manifest details
martha integrations plugins

# Show full plugin detail (manifest, resources, functions, health)
martha integrations plugin martha-scoring

# Make authenticated requests through the plugin proxy
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&active=true"

The proxy command forwards requests through /api/admin/plugins/{name}/{path}, injecting tenant context automatically.