Madnion CLI and server-side SDK

A workspace builder key gives an agent a discovery and configuration API. Platform admin keys remain a separate privileged mode.

Install

# Install the CLI and MCP server
npm install --global @madnion/cli

# Or add the server-side SDK to a Node project
npm install @madnion/cli

Builder quickstart

1. In workspace Settings / API keys, choose Builder. The key starts with wak_builder_.
2. Store it as MADNION_API_KEY in the builder's private environment or secret store. Never use a VITE_ or NEXT_PUBLIC_ variable or paste it into public prompts.
3. Run:

madnion bootstrap
madnion describe apps
madnion apps create --id=app_my_project --name="My Project" --json='{"redirect_uris":["https://example.com/callback"],"allowed_origins":["https://example.com"]}'
madnion connectors list
madnion docs
madnion skills
madnion tools

App creation returns a backend client_secret once. Keep the builder key in the development environment; deployed apps should use their own narrower runtime credentials. Stable app IDs detect duplicates. Inspect existing resources after an uncertain response instead of retrying with a new ID.

HTTP-only builders can POST the same envelope to https://api.madnion.com/functions/v1/builder-api with Authorization: Bearer <builder-key>. This gateway does not require a second Supabase key.

{"resource":"meta","action":"bootstrap","params":{}}

Bootstrap returns workspace identity, action schemas, documentation and required human steps. Use --file=connector.json for provider secrets to keep them out of command-line history. Protect the file and exclude it from version control. Connector and proxy IDs are UUIDs. Connector secrets are write-only. Lists use offset and return next_offset.

Agent-native operation

The CLI exposes the authenticated action catalog as standard, typed tools instead of making an agent guess API routes or dashboard steps:

# Inspect MCP-compatible tool definitions
madnion tools
madnion tools apps

# Execute a discovered tool. stdin is safest for credentials and generated payloads.
printf '%s' '{"offset":0}' | madnion exec madnion_apps_list --stdin

# Start the local stdio MCP server used by Claude, Codex and other MCP clients.
madnion mcp
# The dedicated binary is equivalent:
madnion-mcp

Configure an MCP client to launch madnion mcp and pass MADNION_API_KEY through its private environment. The server dynamically publishes one tool per permitted action, including JSON input schemas and read/write safety hints. It also publishes workspace, catalog, documentation and recent-audit resources; reusable application, audit and webhook prompts; and guarded planning and workflow tools. Environments that cannot launch a local stdio server, including hosted visual builders, can use the same catalog and single-envelope HTTPS API described below.

Agents should read madnion://workspace/context, call madnion_plan_operations, and only then call madnion_execute_workflow. The workflow tool validates all parameters before the first write, runs at most 50 ordered operations, stops on failure by default and refuses destructive plans unless allow_destructive=true. Each destructive API action still requires its own confirmation parameter.

For ordered setup work, batch several operations into one non-interactive workflow:

[
  {"resource":"apps","action":"list","params":{"offset":0}},
  {"resource":"connectors","action":"providers","params":{}}
]

madnion plan --file=operations.json
madnion batch --file=operations.json --dry-run
madnion batch --file=operations.json

Batches run sequentially and stop on the first failure so an agent does not compound a partial setup. Add --continue-on-error only for independent operations. After reviewing a destructive plan, add --allow-destructive; the action's own confirmation field is still required. Results are always structured JSON and include the operation index. Write operations are marked in the live catalog; provider consent, payments, and reviewed proxy activation intentionally remain human actions.

Dashboard-free app operations

The builder API now covers common credential and webhook work that previously required the dashboard:

# App inspection and explicit client-secret rotation
madnion apps get --id=app_my_project
madnion apps rotate_secret --id=app_my_project --confirm=true

# Service-account lifecycle. Keys are returned exactly once.
madnion service_accounts issue --app_id=app_my_project \
  --scopes=email,ai,integrations
madnion service_accounts update --app_id=app_my_project --enabled=false
madnion service_accounts revoke --app_id=app_my_project --confirm=true

# Webhook configuration and delivery diagnostics
madnion webhooks configure --app_id=app_my_project \
  --webhook_url=https://app.example.com/api/webhooks \
  --events=user.created,subscription.updated
madnion webhooks deliveries --app_id=app_my_project --status=failed
madnion webhooks rotate_secret --app_id=app_my_project --confirm=true

Rotating a client secret, replacing an existing service-account key, revoking a key, disabling a webhook, and rotating a webhook secret require explicit confirmation. Read actions return only metadata and prefixes—never stored secrets or webhook payloads.

Available operations

• Workspace discovery, docs and public skill access.
• App listing, creation, redirects and origin updates.
• App inspection and explicit client-secret rotation.
• Service-account issue, status, scopes, enable/disable and revocation.
• Webhook configuration, signing-secret rotation, disablement and delivery diagnostics.
• Provider catalog, OAuth connection metadata and API-key connector creation.
• Workspace proxy listing and private disabled draft creation.

OAuth needs account-holder consent. Stripe setup uses its dedicated flow. Proxy drafts need authentication, actions and outbound destination review before activation. Responses identify those requirements. This release does not claim automated OAuth, custom proxy activation, or full dashboard parity. MCP-capable agents use the native stdio bridge; other agents use the builder HTTPS API.

SDK

import { Madnion } from '@madnion/cli';
const client = new Madnion({ key: process.env.MADNION_API_KEY });
const context = await client.bootstrap();
const apps = await client.call('apps', 'list');
const plan = await client.plan([
  { resource: 'apps', action: 'list', params: { offset: 0 } }
]);
const result = await client.executeWorkflow(plan.operations);

MADNION_ADMIN_KEY=mad_admin_... retains privileged admin API compatibility. Never give platform-admin keys to customer builders. MADNION_API_URL supports staging overrides; HTTPS is required except localhost. Requests reject redirects, time out after 30 seconds, and never automatically retry writes.

Run node --test packages/madnion-cli/test/*.test.mjs from the repository root.

Requirements and support

• Node.js 18 or newer.
• Documentation: https://www.madnion.com/docs/cli
• Issues: https://github.com/series-a-uk/one-trust-hub/issues
• Package: https://www.npmjs.com/package/@madnion/cli