Skip to content

Redocly CLI

Your OpenAPI description lists the operations.
Arazzo tells the story.

generate-arazzo turns an OpenAPI description into an Arazzo file you can lint, extend, and run with redocly respect.

Plain, it writes one workflow per operation, instantly and deterministically. Add --with-ai and the same operations come back as real scenarios, with values flowing between steps.

$ redocly generate-arazzo cafe.yaml
cafe.yaml6 operations
  • POST/oauth2/registerregisterOAuth2Client
  • POST/menucreateMenuItemOAuth2
  • GET/menulistMenuItems
  • GET/menu-item-images/{menuItemId}getMenuItemPhoto
  • DELETE/menu/{menuItemId}deleteMenuItemOAuth2
  • GET/revenuegetRevenueOAuth2

one workflow per operationsecurity inputs included

auto-generated.arazzo.yamlskeleton
post-oauth2-register-workflow
  1. 1
    POST/oauth2/register
post-menu-workflow
  1. 1
    POST/menu
get-menu-workflow
  1. 1
    GET/menu
get-menu-item-images-{menuItemId}-workflow
  1. 1
    GET/menu-item-images/{menuItemId}
delete-menu-{menuItemId}-workflow
  1. 1
    DELETE/menu/{menuItemId}
get-revenue-workflow
  1. 1
    GET/revenue

6 workflows · 1 step each generated deterministically, no model involvedFlip the switch to compare

Two modes, one file

The skeleton is the safe default. The scenarios are the reason to run it.

Plain generate-arazzo gives you a valid Arazzo file for every OpenAPI description, every time. --with-ai spends a little time and your own AI CLI to write the parts you used to wire by hand.

By hand

engineer + editor
Time to a first file
Hours for one realistic scenario
Workflow shape
Whatever you have time to write
Data between steps
Wired by hand
Security
Written per step
Payloads
Written per step
Same output every run
Yes
Runs without editing
When you are done

generate-arazzo

deterministic skeleton
Time to a first file
Instant
Workflow shape
One workflow per operation
Data between steps
None. Operations do not know each other
Security
x-security and inputs for every scheme the operation declares
Payloads
None
Same output every run
Yes
Runs without editing
Only steps with no dependencies

generate-arazzo --with-ai

designed scenarios
Time to a first file
Seconds to about half a minute
Workflow shape
Multi-step lifecycles, at most --max-workflows of them
Data between steps
Outputs and runtime expressions, wired by the AI
Security
Kept, plus the registration step when the API has one
Payloads
Satisfy the request schemas
Same output every run
No. Marked as AI-inferred, review before use
Runs without editing
After you replace the input placeholders

How it works

Generate, design, verify, run

The skeleton alone is a valid starting point. Design is opt-in, and every AI answer goes through the same checks before it replaces a single line.

  1. 01
    Generate

    Start from any OpenAPI description

    A local file or a URL. The description is bundled and every operation becomes a workflow with one step, the success code of its first documented response, and the x-security setup and inputs its security schemes require.

    $ redocly generate-arazzo openapi.yamlauto-generated.arazzo.yaml · skeleton
    generate-arazzo command
  2. 02
    Design

    Optionally, let your AI CLI write the scenarios

    With --with-ai, the skeleton and the description go to the AI CLI already on your machine: claude, codex, or cursor. It groups related operations into lifecycles, passes values between steps, and fills payloads that satisfy the schemas. Cap the result with --max-workflows.

    $ redocly generate-arazzo openapi.yaml --with-ai --max-workflows 5auto-generated.arazzo.yaml · designed
  3. 03
    Verify

    Accept only what passes the checks

    The answer keeps the baseline arazzo, info, and sourceDescriptions, references only operations that exist, stays within the workflow limit, and passes the spec ruleset. Otherwise the skeleton is written instead, with the reason in the output. You always get a valid file.

    › AI designed 3 workflow(s) (claude).valid Arazzo, every run
    lint command
  4. 04
    Run

    Copy the printed command and execute it

    After writing the file, the command prints a ready-to-run redocly respect command with an --input placeholder for every workflow input. Replace the placeholders with real values and the workflows run against the live API.

    $ redocly respect auto-generated.arazzo.yaml --input <name>=YOUR_<NAME>one --input per workflow input
    redocly respect command

Inside a designed workflow

Follow a value from the step that creates it to the step that deletes it

Hover any expression in the file to see what it means and where it comes from. Then watch how redocly respect executes the workflow, step by step, resolving each expression against the live API.

auto-generated.arazzo.yamldesigned with AI · excerpt
workflows:
- workflowId: manage-menu-items
summary: Create, view, and remove menu items
inputs:
$ref:
steps:
- stepId: register-oauth2-client
operationId:
requestBody:
contentType: application/json
payload:
client_name: pos-terminal
grant_types: [client_credentials]
successCriteria:
- condition:
- stepId: create-menu-item
operationId:
x-security:
- schemeName: OAuth2
values:
accessToken:
requestBody:
contentType: multipart/form-data
payload:
name: Cappuccino
price: 4500
category: beverage
volume: 250
containsCaffeine: true
photoTextDescription: A hot cappuccino in a white ceramic cup.
successCriteria:
- condition:
outputs:
menu-item-id:
- stepId: get-menu-item-photo
operationId:
parameters:
- name: menuItemId
in: path
value:
successCriteria:
- condition:
- stepId: delete-menu-item
operationId:
x-security:
- schemeName: OAuth2
values:
accessToken:
parameters:
- name: menuItemId
in: path
value:
successCriteria:
- condition:

redocly respect run

  1. ·
    POST/oauth2/register
  2. ·
    POST/menu
  3. ·
    GET/menu-item-images/prd_01jb4rx…
  4. ·
    DELETE/menu/prd_01jb4rx…
  5. 4 steps · 4 passed · exit code 0
$response.body#/id

Step output

A JSON Pointer into this step's response body. redocly respect stores the value as output menu-item-id, so any later step can read it. The skeleton never captures anything. The AI added this because a later step needs it.

In this runrun the workflow to resolve it

The answer is never trusted blindly.

--with-ai can change the workflows. It cannot change what they point at.

The file is accepted only if:

  1. arazzo, info, and sourceDescriptions come from the generated baseline
  2. every step references an operation that exists in the OpenAPI description
  3. the workflow count stays within --max-workflows
  4. the result passes validation with the spec ruleset

4

checks every AI answer must pass before it is written

0

API keys to configure. The AI CLI on your machine does the work

1

valid file, always. A rejected answer keeps the skeleton

10

workflows at most by default. A ceiling, not a target

Large descriptions

Too big for one prompt? Two phases, no manual splitting.

When a description does not fit a single prompt, --with-ai switches mode automatically. The AI first picks scenarios from a compact index of every operation, then designs each workflow from only its own operations, in parallel.

Phase 1Select scenarios from the operation index

  1. POST/repos/{owner}/{repo}/issues
  2. GET/repos/{owner}/{repo}/issues/{issue_number}
  3. PATCH/repos/{owner}/{repo}/issues/{issue_number}
  4. GET/repos/{owner}/{repo}/pulls
  5. POST/user/repos
  6. GET/repos/{owner}/{repo}
  7. DELETE/repos/{owner}/{repo}
  8. GET/orgs/{org}/members
  9. POST/gists
  10. GET/gists/{gist_id}
  11. DELETE/gists/{gist_id}
  12. GET/search/code
  13. … 1,190 more operations, one line each

Phase 2Design each scenario from its own operations

issue-lifecycle
  1. 1POST/repos/{owner}/{repo}/issues
  2. 2GET/repos/{owner}/{repo}/issues/{issue_number}
  3. 3PATCH/repos/{owner}/{repo}/issues/{issue_number}
repository-lifecycle
  1. 1POST/user/repos
  2. 2GET/repos/{owner}/{repo}
  3. 3DELETE/repos/{owner}/{repo}
gist-lifecycle
  1. 1POST/gists
  2. 2GET/gists/{gist_id}
  3. 3DELETE/gists/{gist_id}

Designed --ai-concurrency at a time (default 4). A scenario whose design is rejected is skipped, the accepted ones still land in the file. The scenarios shown are an illustration: the AI picks them, and they vary between runs.

12.9 MBGitHub REST description
1,200+operations in the index
3lifecycle workflows designed
~30 send to end

Frequently asked questions

No. Without “--with-ai” the command is deterministic, runs instantly, and sends nothing anywhere. You get one workflow per operation with the security setup each operation requires. The AI option only redesigns those workflows into multi-step scenarios.

Start with the description
you already have.

Three commands from an OpenAPI description to workflows running against the live API. Try it on the hosted Redocly Cafe description first, then point it at your own. Drop --with-ai for the instant skeleton.

  1. 1$ npm i -g @redocly/cli@latest
    Redocly CLI install guide
  2. 2$ redocly generate-arazzo 'https://cafe.redocly.com/_bundle/openapi/cafe.yaml' --with-ai --max-workflows 3
    Generate-arazzo command docs
  3. 3$ redocly respect auto-generated.arazzo.yaml
    Respect command docs

    Append the --input flags that the generate command printed, one per workflow input.

  4. 4Run the workflows in CI with RespectExecute the generated file against the live API on every pull request and fail the build the moment a step breaks.