Automation

CmdCal's API-first design makes it straightforward to generate presentations as part of automated workflows -- CI/CD pipelines, scheduled jobs, or event-driven systems.

API Key Setup

Create a dedicated API key for your automation environment from /dashboard/api-keys. Name it after the system it serves (e.g. "GitHub Actions", "Jenkins Pipeline"). Store the key as an environment secret -- never commit it to source control.

GitHub Actions Example

Generate a presentation on every push to main:

YAML

name: Generate Board Deck
on:
  push:
    branches: [main]
    paths: [data/board-metrics.json]

jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Render presentation
        run: |
          curl -X POST https://api.paperjsx.com/api/v2/render \
            -H "Authorization: Bearer ${{ secrets.PAPERJSX_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d @data/board-spec.json \
            -o render-response.json

      - name: Poll for completion
        run: |
          JOB_ID=$(jq -r '.data.job_id' render-response.json)
          for i in $(seq 1 30); do
            STATUS=$(curl -s \
              -H "Authorization: Bearer ${{ secrets.PAPERJSX_API_KEY }}" \
              "https://api.paperjsx.com/api/v2/jobs/$JOB_ID" \
              | jq -r '.job.status')
            if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then
              echo "Job finished with status: $STATUS"
              break
            fi
            sleep 2
          done

Render-on-Merge Pattern

Use approvalRequired: true with a baselineJobId to create a review gate:

On PR merge, submit a render with the previous approved job as the baseline.
The new job enters needs_review status with a diff summary.
A reviewer approves or rejects from the dashboard.
Your pipeline checks approval_status before deploying the artifact.

JSON

{
  "sourceSchema": "protocol_v2",
  "mode": "async",
  "approvalRequired": true,
  "baselineJobId": "job_previous_approved",
  "document": { ... }
}

Scheduled Renders

For recurring reports (weekly metrics, monthly board decks), use a cron-triggered workflow:

YAML

on:
  schedule:
    - cron: '0 8 * * 1'  # Every Monday at 08:00 UTC

Fetch your latest data, build the PresentationSpec payload, and submit it to /api/v2/render.

Preflight in CI

Run preflight checks as a CI gate to catch quality issues before rendering:

Terminal

curl -X POST https://api.paperjsx.com/api/v2/preflight \
  -H "Authorization: Bearer $PAPERJSX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @spec.json > preflight.json

SCORE=$(jq '.data.quality_report.deckScore' preflight.json)
if [ "$SCORE" -lt 70 ]; then
  echo "Deck score $SCORE is below threshold"
  exit 1
fi

MCP Server Integration

For AI agent workflows, configure the CmdCal MCP server in your Claude Desktop or Cursor config:

JSON

{
  "mcpServers": {
    "cmdcal": {
      "command": "npx",
      "args": ["-y", "@paperjsx/mcp-server"],
      "env": {
        "PAPERJSX_API_KEY": "pj_live_YOUR_KEY"
      }
    }
  }
}

Next Steps

API Keys -- create keys for your CI environment
Render Jobs -- understand job states your automation should handle
Review Loop -- add approval gates to automated pipelines
Webhooks -- get notified when jobs complete instead of polling