Can I install UseArazzo CLI today?

Yes. Run npm install --global @usearazzo/cli, or use npx @usearazzo/cli without installing. It is published as an alpha, so options and output may still change before the stable release.

How do I validate an Arazzo document from the command line?

Run npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml. It prints every problem with its location, severity, and rule code, and exits with 1 when there is an error. The argument can also be an HTTP(S) URL.

Can it run workflows?

Not yet. A run-workflow command will wrap the Runner, which is still in development. Discovery commands are an idea too: analyze-workflow would read a workflow and write a profile of the inputs, credentials, and server variables needed to run it.

Which Arazzo versions does it support?

Arazzo 1.0.0, 1.0.1, and 1.1.0, in JSON and YAML.

Yes. Like the rest of the toolkit, UseArazzo CLI is free, open-source, and licensed under Apache 2.0.

UseArazzo CLI

Name: UseArazzo CLI
Author: UseArazzo

Published

One command-line interface across the toolchain, for your terminal and your CI pipeline.

@usearazzo/cli puts the toolkit behind a single usearazzo binary. Its first command, validate, checks an Arazzo document, local file or remote URL, and prints every problem with its line, its severity, and the rule it broke. The exit code tells your pipeline whether to stop.

Read the CLI reference View source on GitHub

Supported versions:

✓ Arazzo 1.0.0, 1.0.1, 1.1.0

From the Terminal

Two documents, two runs. The first has two steps with the same ID, which is an error. The second has a step without a description, which is a warning: advice, not a violation.

usearazzo validate

$ npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml
adopt-a-pet.arazzo.yaml
  16:9-18:38  error  9040403  Every step must have a unique 'stepId' within a workflow.
  19:9-22:1   error  9040403  Every step must have a unique 'stepId' within a workflow.

✖ 2 problems (2 errors)$ npx @usearazzo/cli validate onboarding.arazzo.yaml
onboarding.arazzo.yaml
  16:9-18:1  warning  9050201  Step 'description' should be present and non-empty string.

⚠ 1 problem (1 warning)

Lines and columns count from 1, so you can jump straight to them in your editor. The number in the third column is the rule's code; the Validator reference lists every rule.

In CI

The exit code is the contract. The first run above exits with 1, the second with 0, because by default only errors fail a run. A pipeline needs nothing more than the command. Here it is as a complete GitHub Actions workflow, saved as .github/workflows/arazzo.yml:

# .github/workflows/arazzo.yml
name: Arazzo
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - name: Validate Arazzo workflows
        run: npx @usearazzo/cli validate workflows/adopt-a-pet.arazzo.yaml

Choose what fails

--fail-severity warning makes warnings fail the run too. Run the second document with it, and it exits with 1.

Hand it to another tool

--json prints the problems as Language Server Protocol diagnostics, and -o writes them to a file.

Keep the log short

--max-problems 10 prints the first ten. The exit code still counts all of them, so a cap never hides a failure.

Set it once

A usearazzo.yaml in the working directory holds your validation settings, so every run and every teammate uses the same ones.

Every option, the configuration file, and the JSON format are in the CLI reference.

Commands

Every command delegates to a toolkit library, so the CLI and the libraries always agree. One command ships today. The rest are proposed in toolkit #84, and their names and flags may still change.

validate

Published

usearazzo validate <uri>

Check an Arazzo document, given as a path, a file: URI, or an HTTP(S) URL, and report every problem with the location that caused it. This is @usearazzo/validator behind a command.

Execution

In development

usearazzo run-workflow <uri> <workflowId> --inputs <json|@file>
usearazzo run-operation <uri> --operation-id <id>

Run a workflow against live APIs and print the result of each step in run order, alongside the workflow's outputs and final status. Or run a single OpenAPI operation, with no Arazzo document at all. Both will be @usearazzo/runner behind a command, and they arrive once the Runner is published.

Discovery

Idea

A workflow document tells you what the steps are, but not what you have to bring to run it. Today that means reading the Arazzo document and every OpenAPI source description it pulls in, then assembling credentials and inputs by hand. Three commands could do that reading for you:

usearazzo list-workflows <uri>
usearazzo describe-workflow <uri> <workflowId>
usearazzo analyze-workflow <uri> <workflowId>

list-workflows lists the workflows a document offers. analyze-workflow writes an execution profile: a YAML file with an empty slot for everything the run needs, ready to fill in and pass to run-workflow. describe-workflow prints the same profile for people to read. The profile covers:

Inputs the workflow declares, with their schema
Inputs of every dependsOn workflow, transitively. Arazzo gives dependsOn no way to map inputs inside the document, so a prerequisite that needs inputs can only be fed from outside it
Credentials, from the security schemes of each source description, with the steps that use each one
Server variables, where a source description has a templated base URL

The point is the boundary: what you must provide, separated from what the workflow computes for itself. The profile needs new work in the Runner first (toolkit #82), so if it would help, or if the shape is wrong, now is the time to say so.

Opinions welcome while it is still cheap to change. If you run Arazzo documents in CI, or want particular flags, output formats, or commands, say so in Discussions and it will shape what gets built.

Installation

npm install --global @usearazzo/cli

Or run it without installing:

npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml

Every option, the exit codes, and the configuration file are in the CLI reference.

Built With

Validator

Semantic validation and linting. The validate command is a thin wrapper around it.

Explore Validator

Runner

Step-by-step workflow execution against live APIs. The planned run-workflow and run-operation commands will be thin wrappers around it.

Explore Runner

The Validator builds on @usearazzo/parser, and the Runner on both the parser and @usearazzo/resolver, the toolkit's lower-level packages.

Frequently Asked Questions

: Yes. Run npm install --global @usearazzo/cli, or use npx @usearazzo/cli without installing. It is published as an alpha, so options and output may still change before the stable release.
: Run npx @usearazzo/cli validate adopt-a-pet.arazzo.yaml. It prints every problem with its location, severity, and rule code, and exits with 1 when there is an error. The argument can also be an HTTP(S) URL.
: Not yet. A run-workflow command will wrap the Runner, which is still in development. Discovery commands are an idea too: analyze-workflow would read a workflow and write a profile of the inputs, credentials, and server variables needed to run it.
: Arazzo 1.0.0, 1.0.1, and 1.1.0, in JSON and YAML.
: Yes. Like the rest of the toolkit, UseArazzo CLI is free, open-source, and licensed under Apache 2.0.