{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"generate-arazzo","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["generate-arazzo"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Auto-generate Arazzo workflows based on an OpenAPI description file."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given the nature of OpenAPI, the generated Arazzo description is not a complete test file and may not function."," ","Dependencies between endpoints are not resolved without using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--with-ai"]}," option."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It acts as a starting point for a test file and needs to be extended to be functional."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After writing the file, the command prints a ready-to-run ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/commands/respect"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["respect"]}]}," command, including an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--input"]}," placeholder for every workflow input."," ","Before running the command, replace the placeholder values with real ones."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--with-ai"]},", the generated one-workflow-per-operation skeleton is redesigned by an AI provider into realistic multi-step workflows, using the OpenAPI description as context."," ","See the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#redesign-workflows-with-ai"},"children":["Redesign workflows with AI"]}," section."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage","__idx":1},"children":["Usage"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"redocly generate-arazzo <api>\nredocly generate-arazzo <api> --with-ai -o <outputName>\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":2},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["api"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Path to the API description file you want to generate Arazzo workflows from."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["-o, --output-file"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Name for the generated output file. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto-generated.arazzo.yaml"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["If the file already exists, it's overwritten."]}," See the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#specify-output-file"},"children":["specify output file"]}," section."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--with-ai"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Redesign the generated workflows with an AI provider, using the OpenAPI description as context. Default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"See the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#redesign-workflows-with-ai"},"children":["redesign workflows with AI"]}," section.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Without this option, only the first HTTP response is used as the success criteria for each step."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--ai-provider"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["AI provider used with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--with-ai"]},". Runs the corresponding CLI in non-interactive mode.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claude"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["codex"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]},". Default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claude"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--ai-model"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Model passed to the selected AI provider. If not set, the provider's default model is used."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--ai-concurrency"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of workflows designed in parallel with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--with-ai"]}," when a large description is handled in two phases. Default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--max-workflows"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Most workflows the AI may design with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--with-ai"]},". The output contains the most likely scenarios instead of every combination. Default: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":3},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run the command: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly generate-arazzo 'https://cafe.redocly.com/_bundle/openapi/cafe.yaml'"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The command generates an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto-generated.arazzo.yaml"]}," file in the current directory."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The generated file contains one workflow per operation, with the security setup each operation requires."," ","A shortened excerpt:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"auto-generated.arazzo.yaml","header":{"title":"auto-generated.arazzo.yaml","controls":{"copy":{}}},"source":"arazzo: 1.1.0\ninfo:\n  title: Redocly Cafe\n  version: 1.0.0\nsourceDescriptions:\n  - name: cafe\n    type: openapi\n    url: https://cafe.redocly.com/_bundle/openapi/cafe.yaml\nworkflows:\n  - workflowId: post-menu-workflow\n    inputs:\n      $ref: '#/components/inputs/OAuth2'\n    steps:\n      - stepId: post-menu-step\n        operationId: $sourceDescriptions.cafe.createMenuItem\n        x-security:\n          - schemeName: OAuth2\n            values:\n              accessToken: $inputs.OAuth2\n        successCriteria:\n          - condition: $statusCode == 201\n  - workflowId: get-menu-workflow\n    steps:\n      - stepId: get-menu-step\n        operationId: $sourceDescriptions.cafe.listMenuItems\n        successCriteria:\n          - condition: $statusCode == 200\n  - workflowId: get-revenue-workflow\n    inputs:\n      $ref: '#/components/inputs/ApiKey'\n    steps:\n      - stepId: get-revenue-step\n        operationId: $sourceDescriptions.cafe.getRevenue\n        x-security:\n          - schemeName: ApiKey\n            values:\n              apiKey: $inputs.ApiKey\n          - schemeName: OAuth2\n            values:\n              accessToken: $inputs.OAuth2\n        successCriteria:\n          - condition: $statusCode == 200\n  # ...one workflow like these for every other operation\ncomponents:\n  inputs:\n    OAuth2:\n      type: object\n      properties:\n        OAuth2:\n          type: string\n          description: OAuth2 authorization for API access.\n          format: password\n    ApiKey:\n      type: object\n      properties:\n        ApiKey:\n          type: string\n          description: API key for internal operations.\n          format: password\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The generated file is not a complete test file and needs to be extended to be functional."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specify-output-file","__idx":4},"children":["Specify output file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, the CLI tool writes the generated file as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto-generated.arazzo.yaml"]}," in the current working directory. Use the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--output-file"]}," argument to provide an alternative output file path."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly generate-arazzo <your-OAS-description-file> --output-file=arazzo-custom.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redesign-workflows-with-ai","__idx":5},"children":["Redesign workflows with AI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Without AI, the generated file contains one workflow per operation and no dependencies between them."," ","With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--with-ai"]},", the OpenAPI description and the generated skeleton are sent to an AI provider, which redesigns the workflows into realistic scenarios:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Related operations are grouped into multi-step workflows (for example: create, read, update, then delete a resource)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Steps pass values to each other through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outputs"]}," and runtime expressions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Workflows declare ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inputs"]}," for values a caller must provide."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The AI designs at most ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--max-workflows"]}," workflows (default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]},"), preferring to cover every operation and otherwise choosing the most likely scenarios."," ","The AI's answer is never trusted blindly:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arazzo"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceDescriptions"]}," must come from the generated baseline"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["every step must reference an existing operation in the OpenAPI description"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["workflow count must stay within ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--max-workflows"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the result must pass validation with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spec"]}," ruleset"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Large descriptions that don't fit a single prompt are handled in two phases:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The AI chooses up to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--max-workflows"]}," scenarios from a compact operation index."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The AI designs each scenario's workflow from only its operations."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This two-phase mode skips scenarios whose design is rejected, and the accepted workflows are included in the output."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The command keeps the auto-generated workflows even if:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the answer is rejected"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the provider fails"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the operation index is too large to prompt with"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The generated file starts with a comment marking the workflows as AI-inferred."," ","The workflows are a guess derived from the description, not verified behavior."," ","Review them before use."," ","The result also varies between runs: the same description can produce different workflows each time."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly generate-arazzo openapi.yaml --with-ai --ai-provider claude --max-workflows 5\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Data sharing"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--with-ai"]}," sends the resolved OpenAPI description to the selected AI provider."," ","Make sure it contains no secrets or personal data you are not allowed to share."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"ai-providers","__idx":6},"children":["AI providers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The workflows are designed by a locally installed AI CLI running in non-interactive mode: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claude"]}," (Claude Code), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["codex"]}," (Codex CLI), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor"]}," (Cursor CLI)."," ","The selected CLI must be installed and authenticated on the machine running the command."," ","No API key is passed to or stored by Redocly CLI."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The provider runs in isolation: project context the CLIs normally load (such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLAUDE.md"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AGENTS.md"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".cursor/rules"]},") and settings like a configured model do not apply."," ","Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--ai-model"]}," to choose a model, or the provider's default is used."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":7},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/commands/respect"},"children":["Respect command"]}," to execute your Arazzo description."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/learn/arazzo/what-is-arazzo"},"children":["Learn more about Arazzo"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/blog/generate-arazzo-with-ai"},"children":["Generate realistic Arazzo workflows with AI"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/lint"},"children":["Lint command"]}," to lint your Arazzo description."]}]}]},"frontmatter":{"slug":["/docs/cli/commands/generate-arazzo","/docs/respect/commands/generate-arazzo"]},"tagList":["admonition","html"],"title":"generate-arazzo","lastModified":"2026-09-29T11:18:13.000Z"}