Skip to content

Arazzo Runner – Getting Started

Goal – Run any Jentic Public APIs workflow or single OpenAPI operation locally from the command line, no server or cloud account required.

1. What you’ll get

CLI command What it does
list-workflows <file> Show IDs + summaries inside an Arazzo file
describe-workflow <file> --workflow-id ID Detailed view of one workflow
execute-workflow … Run a multi-step workflow described in an Arazzo file
execute-operation … Invoke a single operationId from an OpenAPI spec
show-env-mappings … Print required auth environment variables
generate-example … Output a ready-to-run CLI example

For full release notes see the arazzo-runner page on PyPI.

2. Before you start

You need Why Quick install
Python ≥ 3.11 Runtime for arazzo-runner python.org
arazzo-runner The CLI execution engine pip install arazzo-runner
Jentic Public APIs specs Workflows/OpenAPI files to run Clone everything → git clone https://github.com/jentic/jentic-public-apis.git
or grab one file via curl -LO …
Auth tokens Many APIs need tokens/keys Docs below show how to export e.g. DISCORD_BOTTOKEN

Using PDM inside the repo? Prefix any command with pdm run, e.g. pdm run python -m arazzo-runner list-workflows ….

Quick Start

1. Get the specs or workflows

Source When to choose Command
Clone the full catalog You want everything offline git clone https://github.com/jentic/jentic-public-apis.git
Fetch one file You only need a single integration curl -L -o workflows.arazzo.json https://raw.githubusercontent.com/jentic/jentic-public-apis/main/workflows/discord.com/workflows.arazzo.json
Write your own You have a private API Create a small YAML/JSON file (examples below)

Arazzo Runner expects a local path, so download or create a file first.

Need the exhaustive parameter reference? You’ll find a complete table for every CLI flag and environment variable in the arazzo-runner page on PyPI under Command Line Usage.

2. Execute a Workflow

Run a workflow directly from the command line.

pdm run python -m arazzo-runner execute-workflow workflows/discord.com/workflows.arazzo.json --workflow-id get-authenticated-user-details

3. Show Required Environment Variables

Discover which environment variables are needed for authentication:

pdm run python -m arazzo-runner show-env-mappings workflows/discord.com/workflows.arazzo.json

pdm run python -m arazzo-runner show-env-mappings --openapi-path=apis/openapi/discord.com/main/10/openapi.json

4. List Available Workflows

pdm run python -m arazzo-runner list-workflows workflows/discord.com/workflows.arazzo.json

5. Describe a Workflow

pdm run python -m arazzo-runner describe-workflow workflows/discord.com/workflows.arazzo.json \
  --workflow-id get-authenticated-user-details

6. Generate an Example CLI Command

pdm run python -m arazzo-runner generate-example workflows/discord.com/workflows.arazzo.json \
  --workflow-id get-authenticated-user-details

7. Run a single OpenAPI operation

Run a single OpenAPI operation by operationId:

pdm run python -m arazzo-runner execute-operation --openapi-path apis/openapi/notion.so/2022.06.28/openapi.json \
  --operation-id retrievePage \
  --inputs '{"page_id": "…"}'

Or by HTTP method and path (with Arazzo context):

pdm run python -m arazzo-runner execute-operation --arazzo-path workflows/discord.com/workflows.arazzo.json \
  --operation-path 'GET /users/@me/guilds' \
  --inputs '{}'

Set your environment variables once per shell (or in CI):

export DISCORD_BOTTOKEN="<your-discord-bottoken>"

Python Library (API Usage)

Prefer Python over the CLI? Import ArazzoRunner and point it at either an Arazzo workflow file or an OpenAPI spec:

from arazzo_runner import ArazzoRunner

# 1️⃣  Run a full workflow
runner = ArazzoRunner.from_arazzo_path("workflows/discord.com/workflows.arazzo.json")
result = runner.execute_workflow("get-authenticated-user-details", {
    # input params here (if any)
})
print(result)

# 2️⃣  Call a single OpenAPI operation
runner = ArazzoRunner.from_openapi_path("apis/openapi/notion.so/2022.06.28/openapi.json")
page = runner.execute_operation("retrievePage", {"page_id": "…"})
print(page)

The Python API exposes the same capabilities as the CLI while letting you integrate Jentic Public APIs calls inside larger programs or agents.

Authoring Cheatsheet

Minimal Arazzo

openapi:
  jsonph: https://jsonplaceholder.typicode.com/openapi.yaml

workflows:
  getUserPosts:
    inputs: { userId: integer }
    steps:
      - id: user
        call: jsonph::GET /users/{id}
        params: { id: $inputs.userId }
      - id: posts
        call: jsonph::GET /posts
        params: { userId: $steps.user.response.id }
    output: $steps.posts.response

Tiny OpenAPI

openapi: 3.1.0
info: { title: Echo API, version: 1.0 }
paths:
  /echo:
    post:
      operationId: echoIt
      requestBody:
        required: true
        content: { application/json: { schema: { type: object } } }
      responses:
        '200': { description: echoed, content: { application/json: { schema: { type: object } } } }

Troubleshooting

Run python -m arazzo_runner --help or python -m arazzo_runner <cmd> --help for options.

Symptom Fix
ModuleNotFoundError Activate the venv you installed into.
arazzo_runner.errors.AuthError Run show-env-mappings, export missing token.
FileNotFoundError Use a local path; download the spec first.