Redocly recently released a wonderful open-source tool that works with OpenAPI that promises to deliver the power of the command line interface (CLI) to the hands of API developers. Beyond being a joy to work with, it’s extremely powerful, packing reams of customization under the hood. Below, we’ll take a look at Redocly CLI and see just what the use case and utility of the solution are!

What is Redocly CLI?

Redocly CLI is a deceptively simple tool that recently launched into a stable 1.0 release. On the face of things, it’s a simple command-line tool. However, once you dig a bit deeper, you’ll find a lot packed into this CLI that makes it a strong offering. Redocly CLI aims to be a handy API management system with a relatively complete toolkit, including specification, generation, and documentation.

One central reason to consider Redocly CLI is the fact that it is open source. While it boasts easy integration and manipulation of OpenAPI, the fact that Redocly CLI itself is open source is a major plus. In general, well-supported open source tends to lead to good security, community review, and remixing and iteration based on branching development paths.

Why CLI?

Before we dive into specific features, we should note that working exclusively from a CLI might be a negative for some users. However, CLI solutions are often the most appropriate tool for a wide range of use cases and are often quite simple in practical application once you get used to it.

While there is a learning curve, a simple textual interface can create more streamlined interactions and result in quite a bit more control. This is a big reason that CLIs are so beloved by developers — they are simple, powerful, and extensible.

How to Use Redocly CLI

There are a handful of installation methods currently documented in the Redocly CLI docs.

Docker

For many users, the easiest method will be the Docker method. To do this, simply pull up a Docker instance and run the following command:

docker pull redocly/cli

After this, simply move the OpenAPI definition file into the working directory and mount using the following command:

docker run --rm -v $PWD:/spec redocly/cli lint spec.yaml

Local Install

If you prefer to install locally, that’s quite easy to do. One way to go about this is to use npm to install the package via the following command:

npm i -g @redocly/cli@latest

You could also use yarn to accomplish this:

yarn global add @redocly/cli

Either way, once this is installed, you can use the redocly --version command to confirm the installation.

Runtime Using npx

You can also run Redocly CLI as a runtime package rather than installing it locally. To do so, you can use the npx command as follows:

npx @redocly/cli <command> [options]

Common Use Cases

From here, there’s a handful of commands that you will find to use. Redocly CLI separates them broadly into five different categories.

Documentation Commands

• preview-docs lets users preview the API reference documentation for a specified definition. This preview will run via http://localhost:8080, but this can be changed via the -p flag, which allows for a custom port. An example of what this looks like is below.

• build-docs allows for building an HTML file based on the definition. Using a variety of flags (most notably template.Options), additional elements can be inserted into the HTML build to render content in a specific way.

API Management Commands

• stats gathers document statistics and presents the data in a given format. Options include specifying a custom configuration file or changing the output format.
• bundle is a wonderful feature that allows users to bundle files for separate reusable parts, bridging the gap between a microservices approach and the single-file API definition restriction common to OpenAPI implementations.
• split is the exact opposite of bundle, allowing for creating multiple files from a single specification.

Linting Commands

• lint is an error reporting function that identifies and reports problems within OpenAPI definitions for developers to fix. Specific files can be targeted or excluded from this process, allowing for relatively granular error discovery and correction.

Redocly Platform Commands

• login and logout do exactly what you’d think they do — they allow you to log in and log out of the Redocly API registry with an access token and clear said credentials upon logout.
• push is, again, what it says on the tin — push a definition to the API registry!

Supporting Commands

• completion generates auto-complete commands.

Definition Checks

The linting process was briefly covered a moment ago, but it is perhaps the best part of Redocly CLI. Linting is the process of ensuring that the OpenAPI description matches the accepted best practices. Redocly CLI provides this as a native solution, utilizing both existing default rulesets as well as custom rulesets to be measured against the sampled description.

It should be noted that this approach does have one particular weakness: the linting output will only be as good as the ruleset provided. Redocly makes it very clear that the two rulesets provided are very opinionated as opposed to perfect, noting in the documentation the following:

“Our recommended ruleset is our unabashedly opinionated recommendation of what we think a good API looks like. It’s a great place to start, before adapting to your own context… A minimal ruleset is a good starting point for an existing API that doesn’t currently conform to any standard. It has fewer rules that cause an error, with others either downgraded to a warning or turned off completely.”

There are three severity settings for these rule sets, each defining how errors are handled when discovered. “Error” results in an error message that blocks validation, while “warn” simply warns and allows validation. “off” entirely disables the rule and skips validation, which is the same as basically having no rules.

Decoration

Another great thing about Redocly CLI is the ability to utilize Decorators. Simply put, Decorates are modifications to the API description that occur as a pre-bundling process. This process runs through a set of rules and expectations, and, from this configuration, changes the content in the final bundle.

Such changes can update descriptions, change examples, or remove content, and additional Decorators are constantly being iterated based on community feedback. This allows for much more granular control over what the end specification looks like than might seem possible at first blush, and is a big piece of why this works so well in a microservices environment.

Custom Plugins

Finally, Redocly CLI provides a huge benefit in the form of custom plugins. The rules that we’ve discussed in this piece, the relatively spartan set of Decorators, and even the types underpinning Redocly CLI can all be changed through custom plugins for a variety of functional shifts.

This amount of customization aligns with the ethos of a CLI — ultimate control with a steep learning curve — so it’s no surprise that it’s built into the process of Redocly CLI as a default behavior. Being able to do such increasingly custom deployments is valuable as it allows for greater extensibility of the core use case.

Conclusion

What do you think of Redocly CLI? Are there similar tools that you’d like to see reviewed? We at Nordic APIs are always looking for new toolsets to review, so let us know in the comments which one we should look at next!