UseArazzo CLI

In development

One command-line interface across the toolchain: validate and run Arazzo workflows on your machine and in CI.

@usearazzo/cli is meant to be the front door to the toolkit: the same validation and execution engines the libraries expose, wrapped in a single binary for your terminal or CI/CD pipeline. It is the package the rest of this page describes, and it has not shipped yet.

This package does not exist yet. There is no @usearazzo/cli on npm, and no cli package in the arazzo-toolkit monorepo either. Everything below is a design sketch of the interface we intend to build on the Validator and Runner, which are themselves unpublished and under heavy development. Command names, flags, and output are all subject to change. Follow Discussions to hear when it ships.

The two engines it will wrap are being built in the open, and are not published either:

Explore Validator Explore Runner

The shape we are aiming for

Two commands mapped onto the two things the toolkit does as libraries, plus a third we are still thinking through. Nothing here is implemented, and the names are a starting point for discussion rather than a decision.

usearazzo validate <uri>

Check an Arazzo document, local file or remote URL, against the specification, and report every violation with the location that caused it. This is @usearazzo/validator behind a command. 

usearazzo run <uri> <workflowId> --input key=value

Execute a workflow against live APIs and print the trace of each step in run order, alongside the workflow's outputs and final status. This is @usearazzo/runner behind a command.

init

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. A third command could do that reading for you and write an editable configuration file instead:

usearazzo init <uri>

What it would work out from the document and its source descriptions:

  • Inputs the workflow declares, as placeholders to fill in
  • Inputs of every dependsOn workflow, transitively, keyed by workflow. 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
  • Server variables, where a source description has a templated base URL

And what it would mark as not yours to supply: step parameters that resolve from earlier steps, and sub-workflow steps, which map their own inputs through their parameters.

That boundary is the point: separating what you must provide from what the workflow computes for itself. Today the only way to find it is to read the entry document, every workflow it depends on, and every source description they name. This one is genuinely unexplored, so if it would help or if the shape is wrong, that is useful to hear.

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

What has to land first

The CLI is the last piece, not the first. It carries no logic of its own, so it can only be as stable as the two libraries underneath it.

  1. 1 Validator API stabilizes, then publishes to npm
  2. 2 Runner API stabilizes, then publishes to npm
  3. 3 CLI wraps both in a single binary, then publishes to npm

Beyond the CLI, the wider roadmap adds a Language Service, a browser editor, a VS Code extension, GitHub Actions, agent skills, an MCP server, an MCP compiler, and Arazzo transformers. See the full roadmap for what each one is.

Built With

Validator

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

Explore Validator

Runner

Step-by-step workflow execution against live APIs. The planned run command is a thin wrapper around it.

Explore Runner

Both build on @usearazzo/parser and @usearazzo/resolver, the toolkit's lower-level packages.

Frequently Asked Questions

Can I install UseArazzo CLI today?

No. There is no @usearazzo/cli package on npm, and neither the Validator nor the Runner it will wrap has been published yet. The entire toolkit, CLI and Validator and Runner alike, is pre-1.0 and in heavy development.

What will UseArazzo CLI do?

Two commands to begin with: validate checks an Arazzo document against the specification, and run executes a workflow against live APIs and prints the step-by-step trace. Both wrap existing libraries, not new logic. A third, init, is being explored: it would read a workflow and write an editable configuration file covering the inputs, credentials, and server variables needed to run it.

Will it be free?

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

How can I find out when it ships?

Watch or follow the arazzo-toolkit repository, or join GitHub Discussions.