API Documentation & Diagram Generator

run-workflow-weaver

Agent skill for driving the workflow-weaver CLI and MCP server headlessly. Works from any agent runtime that can invoke subprocesses or connect to an MCP host.

Prerequisites

• Node.js ≥ 20
• Global install:

  npm install -g workflow-weaver @workflow-weaver/mcp
  

Authentication

Interactive (recommended for first-time setup):

workflow-weaver auth login --email you@example.com
# Password is prompted interactively — omit --password to avoid exposing it in shell history
***

**Non-interactive (agents / CI):**

Export the token after interactive login:

```bash
node -e "process.stdout.write(require(require('os').homedir()+'/.workflow-weaver/config.json').refreshToken)"

Then set it in the agent's environment:

export WORKFLOW_WEAVER_REFRESH_TOKEN=***

The CLI automatically reads WORKFLOW_WEAVER_REFRESH_TOKEN from the environment. No prefix mapping is needed.

Security

Run (Agent Path)

CLI subprocess pattern

All commands support --json for machine-readable NDJSON output:

workflow-weaver  [args] --json

Exit codes

Core 6-step sequence

# 1. Verify credentials
workflow-weaver auth status --json

# 2. Check quota before generating
workflow-weaver billing status --json

# 3. Create a project
PROJECT=$(workflow-weaver projects create \
  --title "Stripe Guide" \
  --use-case "Payment integration" \
  --json)
PROJECT_ID=$(echo "$PROJECT" | jq -r '.id')

# 4. Add a source
workflow-weaver sources add "$PROJECT_ID" \
  --type snippet \
  --content "GET /users" \
  --json

# 5. Generate (streams progress events as NDJSON, final line is the completed version)
GENERATE_OUTPUT=$(workflow-weaver generate "$PROJECT_ID" --json)
echo "$GENERATE_OUTPUT" | tail -1
VERSION_ID=$(echo "$GENERATE_OUTPUT" | tail -1 | jq -r '.versionId // .id')

# 6. Export
workflow-weaver export "$PROJECT_ID" "$VERSION_ID" --format md

Error handling for agents

On any WorkflowWeaverError (exit code 1), stderr contains JSON:

{ "error": "Project has no sources", "code": "PRECONDITION_FAILED", "statusCode": 400 }

Quota exhaustion / BYOK

When billing status --json returns canGenerate: false:

If byok_active: true, generation is unlimited regardless of plan or credits.

Token rotation gotcha

The refresh token in ~/.workflow-weaver/config.json may be rotated (invalidated and replaced) by the server. Never cache the token by reading the config file directly.

• Always pass the token via WORKFLOW_WEAVER_REFRESH_TOKEN env var
• If you must read from config, re-read before every operation — do not cache
• The CLI handles token refresh internally; let it read from its config file
• When using the env var, each CLI call may rotate the token server-side. The CLI writes the new token to ~/.workflow-weaver/config.json, but the env var still holds the old value. For long-running agent sessions, prefer letting the CLI read from its config file rather than setting the env var persistently

MCP Server Configuration

The MCP server requires three env vars: WORKFLOW_WEAVER_REFRESH_TOKEN, WORKFLOW_WEAVER_SUPABASE_URL, and WORKFLOW_WEAVER_SUPABASE_KEY.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "workflow-weaver": {
      "command": "npx",
      "args": ["@workflow-weaver/mcp@latest"],
      "env": {
        "WORKFLOW_WEAVER_REFRESH_TOKEN": "***",
        "WORKFLOW_WEAVER_SUPABASE_URL": "***",
        "WORKFLOW_WEAVER_SUPABASE_KEY": "***"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "workflow-weaver": {
      "command": "npx",
      "args": ["@workflow-weaver/mcp@latest"],
      "env": {
        "WORKFLOW_WEAVER_REFRESH_TOKEN": "***",
        "WORKFLOW_WEAVER_SUPABASE_URL": "***",
        "WORKFLOW_WEAVER_SUPABASE_KEY": "***"
      }
    }
  }
}

Kiro

Edit .kiro/settings/mcp.json in your workspace:

{
  "mcpServers": {
    "workflow-weaver": {
      "command": "npx",
      "args": ["@workflow-weaver/mcp@latest"],
      "env": {
        "WORKFLOW_WEAVER_REFRESH_TOKEN": "***",
        "WORKFLOW_WEAVER_SUPABASE_URL": "***",
        "WORKFLOW_WEAVER_SUPABASE_KEY": "***"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Note: If you installed @workflow-weaver/mcp globally, you can also use the workflow-weaver-mcp binary directly instead of npx.

MCP Tools (23)

MCP error handling

All tool errors return isError: true with JSON in content[0].text:

{ "code": "INVALID_PARAMS", "message": "project_id is required" }
{ "code": "QUOTA_EXCEEDED", "message": "...", "resolution_paths": [...] }
{ "code": "AUTH_FAILED", "message": "Token is not authenticated" }

Smoke Test

Run offline checks (no token required):

bash .claude/skills/run-workflow-weaver/smoke.sh

Run with live credentials:

WORKFLOW_WEAVER_REFRESH_TOKEN=*** bash .claude/skills/run-workflow-weaver/smoke.sh

Global Flags

Environment Variables