@formant/metaphysics CLI

Metaphysics CLI - AI agent access to the Cortex API.

A JSON-first CLI designed for AI agents to interact with the cortex workflow engine, runs, and agents via Keycloak-authenticated API calls.

Installation

npm install -g @formant/metaphysics

Environment Variables

The CLI can be configured entirely through environment variables. This is the recommended approach for CI/CD and automation.

Required

| Variable | Description | Example | | ---------------------- | ------------------------- | -------------------------------------- | | METAPHYSICS_API_URL | Cortex API base URL | http://localhost:3000/api | | METAPHYSICS_AUTH_URL | Keycloak issuer/authority | http://localhost:3002/realms/formant |

Authentication (choose one)

Option A: Direct Bearer Token | Variable | Description | |----------|-------------| | METAPHYSICS_API_TOKEN | Direct JWT bearer token (skips login) |

Option B: Password Grant (interactive login) | Variable | Description | |----------|-------------| | KEYCLOAK_CLIENT_ID | Keycloak client ID | | KEYCLOAK_USERNAME | Username for password grant | | KEYCLOAK_PASSWORD | Password for password grant |

Option C: Client Credentials (M2M) | Variable | Description | |----------|-------------| | KEYCLOAK_CLIENT_ID | Service account client ID | | KEYCLOAK_CLIENT_SECRET | Service account client secret |

Feature Flags

| Variable | Default | Description | | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | METAPHYSICS_DESTRUCTIVE | false | Enable write/delete commands (create, update, delete, etc). Defaults to off (read-only); set to true to opt in. |

Optional

| Variable | Description | Default | | ----------- | ------------------------------------ | ------- | | LOG_LEVEL | Log level (debug, info, warn, error) | info |

Quick Start

Using Environment Variables

export METAPHYSICS_API_URL=http://localhost:3000/api
export METAPHYSICS_AUTH_URL=http://localhost:3002/realms/formant
export METAPHYSICS_API_TOKEN=eyJhbGciOiJSUzI1NiIs...

metaphysics workflows list
metaphysics runs get run_123

Login with Credentials

export METAPHYSICS_API_URL=http://localhost:3000/api
export METAPHYSICS_AUTH_URL=http://localhost:3002/realms/formant

metaphysics login \
  --client-id cortex-console \
  --username [email protected] \
  --password [email protected]

# Subsequent commands use cached token
metaphysics workflows list
metaphysics runs list

Read-Only Mode (Default)

The CLI is read-only by default. Write/delete commands are hidden from help and rejected at runtime unless explicitly enabled.

metaphysics workflows list      # ✅ Works
metaphysics workflows create    # ❌ Hidden from help, errors if called

# Opt in to destructive commands:
export METAPHYSICS_DESTRUCTIVE=true
metaphysics workflows create -b @workflow.json   # ✅ Works

Commands

Workflows

metaphysics workflows list                           # List all workflows
metaphysics workflows get <id>                       # Get workflow by ID
metaphysics workflows versions <id>                  # List workflow versions
metaphysics workflows input-schema <id>              # Get input JSON schema
metaphysics workflows bundle-export <id>             # Export workflow bundle
metaphysics workflows create --body @workflow.json # Create new workflow
metaphysics workflows update <id> --body @patch.json # Update workflow
metaphysics workflows delete <id>                    # Soft-delete workflow
metaphysics workflows disable <id>                   # Disable workflow
metaphysics workflows enable <id>                    # Enable workflow
metaphysics workflows duplicate <id>                 # Duplicate workflow
metaphysics workflows promote-version <id> --version-id <vid>
metaphysics workflows bundle-import --body @bundle.json

Runs

metaphysics runs list                                  # List all runs
metaphysics runs get <id>                              # Get run by ID
metaphysics runs events <id>                           # List run events
metaphysics runs node-executions <id>                  # List node executions
metaphysics runs costs <id>                            # Get run costs
metaphysics runs create --body @run.json               # Create and enqueue run
metaphysics runs pause <id> --body @pause.json         # Pause run (HITL)
metaphysics runs resume <id> --body @resume.json       # Resume run
metaphysics runs cancel <id>                           # Cancel run

Agents

metaphysics agents list              # List all agents
metaphysics agents get <id>          # Get agent by ID
metaphysics agents create --body @agent.json    # Create agent
metaphysics agents update <id> --body @patch.json # Update agent
metaphysics agents delete <id>       # Soft-delete agent

Auth & System

metaphysics auth me                  # Show current identity
metaphysics system health            # Check API health
metaphysics system queue             # Get queue status
metaphysics system workers           # Get worker status
metaphysics whoami                   # Decode JWT locally
metaphysics config                   # Show cached config

Generic API Access

metaphysics api GET /v1/workflows
metaphysics api POST /v1/runs --body @run.json
metaphysics api GET /v1/runs/run_123/events

JSON Body Input

All create/update commands accept JSON via:

1. Inline JSON: --body '{"name":"test"}'
2. File: --body @workflow.json
3. Stdin: cat workflow.json | metaphysics workflows create --body -

All commands validate JSON against Zod schemas before sending to API.

Configuration File

After login, credentials are cached in ~/.config/metaphysics/config.json:

{
  "apiUrl": "http://localhost:3000/api",
  "authUrl": "http://localhost:3002/realms/formant",
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "tokenExpiresAt": "2026-05-06T18:38:53.406Z",
  "destructive": true
}

Environment variables always override cached config.

Examples

Create a Workflow

metaphysics workflows create --body '{
  "name": "my-workflow",
  "workflowType": "standard",
  "graph": {
    "nodes": [
      {
        "nodeKey": "start",
        "nodeType": "start",
        "config": {},
        "inputMapping": {},
        "outputSchema": {}
      }
    ],
    "edges": []
  }
}'

Trigger a Run

metaphysics runs create --body '{
  "workflowId": "wf_xxxxxxxx",
  "input": { "message": "hello world" },
  "idempotencyKey": "run-001"
}'

Create an Agent

metaphysics agents create --body '{
  "name": "my-agent",
  "instructions": "You are a helpful assistant",
  "modelConfigId": "mc_xxxxxxxx",
  "toolRefs": ["web-search", "calculator"],
  "config": { "temperature": 0.7 }
}'

Validation

All inputs are validated against Zod schemas. Invalid JSON produces helpful errors:

Validation failed:
  - name: Required
  - workflowType: Required
  - graph: Required

Output Format

All commands output JSON for easy parsing:

metaphysics workflows list | jq '.items[0].name'

License

Proprietary - Formant Inc.