Jentic OAK Runner – Getting Started

Goal – Run any OAK 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

2. Before you start

You need	Why	Quick install
Python ≥ 3.10	Runtime for oak-runner	python.org
oak-runner	The CLI execution engine	pip install oak-runner
OAK specs	Workflows/OpenAPI files to run	Clone everything → git clone https://github.com/jentic/oak.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 oak_runner list-workflows ….

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

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/oak.git
Fetch one file	You only need a single integration	curl -L -o workflows.arazzo.json https://raw.githubusercontent.com/jentic/oak/main/workflows/discord.com/workflows.arazzo.json
Write your own	You have a private API	Create a small YAML/JSON file (examples below)

oak-runner expects a local path, so download or create a file first.

2. Execute a Workflow

Run a workflow directly from the command line.

pdm run python -m oak_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 oak_runner show-env-mappings workflows/discord.com/workflows.arazzo.json

4. List Available Workflows

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

5. Describe a Workflow

pdm run python -m oak_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 oak_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 oak_runner execute-operation --openapi-path oak/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 oak_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 OAKRunner and point it at either an Arazzo workflow file or an OpenAPI spec:

from oak_runner import OAKRunner

# 1️⃣  Run a full workflow
runner = OAKRunner.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 = OAKRunner.from_openapi_path("oak/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 OAK 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 oak_runner --help or python -m oak_runner <cmd> --help for options.

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

Contact Us Next