@aiaiai-pt/martha-cli 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
+
+## [0.2.0] — 2026-05-09
+
+First public release on npm.
+
+### Added
+- Published as `@aiaiai-pt/martha-cli` on the public npm registry.
+- `README.md` with install + quickstart.
+- Agent skill reference (`skills/martha-cli/SKILL.md`) bundled inside the npm tarball so agent harnesses can pull it post-install.
+- `prepack` script that builds `dist/` and copies the skill before publishing.
+- Provenance attestation on publish via GitHub Actions OIDC.
+
+### Changed
+- Package name: `martha-cli` → `@aiaiai-pt/martha-cli`.
+- Version bump to mark first published release (the unpublished `0.1.0` was dev-only).
+
+### Notes
+- This is a `0.x` release — CLI flags and JSON output may change between minor versions. Pin a version (`npx -y @aiaiai-pt/martha-cli@0.2.0`) when calling from CI or agent runtimes.
+- Tracking issue: [#292](https://github.com/westeuropeco/martha/issues/292) (third-party + agent-runtime distribution plan).

package/README.md

@@ -0,0 +1,127 @@
+# martha-cli
+
+Terminal-first client for the [Martha](https://martha.nomadriver.co) 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](#agent-integration) below.
+
+## Install
+
+### Run on demand (recommended)
+
+```bash
+npx -y @aiaiai-pt/martha-cli@latest --help
+```
+
+Pin a version when calling from CI or agent runtimes:
+
+```bash
+npx -y @aiaiai-pt/martha-cli@0.2.0 agents list --json
+```
+
+### Install globally
+
+```bash
+npm i -g @aiaiai-pt/martha-cli
+martha --version
+```
+
+Requires Node.js >= 22.
+
+## Quickstart
+
+```bash
+# 1. Configure a profile (interactive wizard ships in 0.3.0; until then edit ~/.martha/config.yaml)
+martha config show
+
+# 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. 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:
+
+```yaml
+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:
+
+```bash
+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:
+
+```bash
+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).
+
+## 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:
+
+```bash
+# After global install
+cat $(npm root -g)/@aiaiai-pt/martha-cli/skills/martha-cli/SKILL.md
+
+# Or via npx (no install)
+npx -y -p @aiaiai-pt/martha-cli@latest sh -c 'cat $(dirname $(which martha))/../lib/node_modules/@aiaiai-pt/martha-cli/skills/martha-cli/SKILL.md' 2>/dev/null
+```
+
+A first-class `martha skill` command lands in 0.3.0.
+
+## Stability
+
+`0.x` releases may change CLI flags or JSON output between minor versions. Pin a version in CI/agent contexts:
+
+```bash
+npx -y @aiaiai-pt/martha-cli@0.2.0 ...
+```
+
+`1.0.0` will commit to a stable contract — see the [tracking issue](https://github.com/westeuropeco/martha/issues/292).
+
+## Development
+
+```bash
+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](https://github.com/westeuropeco/martha) monorepo under `martha-cli/`. PRs welcome.
+
+## License
+
+MIT