Enable Actions

[8ball030]

Please provide an official standalone binary for Redocly CLI. Requiring users to install and maintain a full Node.js runtime is a major friction point, especially in CI, minimal containers, and environments where compiled single-file tools are preferred. A statically bundled executable—or officially supported binaries for common platforms—would make the CLI substantially easier to adopt.

An alternative would be an offically supported pinnable githubactions with the ability to specify the VERSIOn of redocly.

[vadyvas]

Thanks for the issue

We publish a Docker image on every release, so the runner does not need Node:

jobs:
  lint:
    runs-on: ubuntu-latest
    container: redocly/cli:2.49.0
    steps:
      - uses: actions/checkout@v6
      - run: redocly lint openapi.yaml --format=github-actions

• tag 2.49.0 is immutable. To pin harder, append the image digest
• image is public, you do not need credentials
• --format=github-actions writes inline annotations on the pull request.
• same image is on Docker Hub as redocly/cli:2.49.0, with the same digest

https://hub.docker.com/r/redocly/cli
https://github.com/redocly/redocly-cli/pkgs/container/cli

Example: #3064

---

@8ball030 does this option work for you?

If it does not, could you share a few details? We would like to know which operating system and architecture you use in CI, and what blocks the image. It also helps us to know whether you still need a standalone binary

[8ball030]

Hi
Thanks alot for the prompt response.

The issue with this is that to get the rest of the dependencies id need in, id need to install extra stuff to that container.
My flow is basically;
-> install deps (We have quite a lot of deps)
-> perform codegen via make command
-> format lint
-> check diff

At present I use ubuntu on amd64 for the build.

Even without ci, i would love to have a standalone binary as i dont always want to pull in node just to use the super helpful and convenient tool you guys have here.

I coud be wrong, but i don't think i can use a different container just for one step?

With a standalone binary, it would also enable github actions

[vadyvas]

@8ball030
You can put a single step in a container - the rest of the job stays on the runner with all your deps:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ...

      - run: |
          docker run --rm -v "$PWD:/spec" redocly/cli:2.49.0 \
            lint openapi.yaml --format=github-actions

Or as a step action, if you'd rather not write docker run:

      - uses: docker://redocly/cli:2.49.0
        with:
          args: lint openapi.yaml --format=github-actions

Docker is already on ubuntu-latest, so there's nothing to install. Here is the first one in a real run:
https://github.com/Redocly/redocly-cli/actions/runs/33391251688/job/99485157329

Locally you have two options:

Docker - Node stays in the container:

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

Homebrew - shortest, but it installs Node under the hood

brew install redocly-cli

https://formulae.brew.sh/formula/redocly-cli

[8ball030]

I really appreciate you guys being so on the issues and providing such comprehensive answers.
However to be candid, I am very unhappy to include any kind of java script dependencies in production repos, due to the potential for supply chain attacks.
A binary would significantly reduce these concerns

[vadyvas]

@8ball030 A few things:

1. How a binary would protect you from an attack? Asking genuinely - it would hold the same code, only with the runtime bundled in, so we'd like to understand the threat you have in mind
2. Either way, we track potential vulnerabilities on a regular basis and patch them on our side
3. And finally, if you want to be absolutely secure, have a look at Reunite, our enterprise platform.

[8ball030]

Hi @vadyvas

I think we're talking about two slightly different threat models here.

I agree that a binary doesn't magically make a vulnerability in Redocly disappear. If Redocly itself has a vulnerability, the same vulnerable code can obviously exist in the binary.

My concern is specifically the npm installation/dependency supply chain, rather than vulnerabilities in Redocly's own code.

When I add an npm package to a production repository, I'm not just trusting redocly-cli. I'm trusting the entire transitive dependency tree, the package versions that get resolved, and the npm installation process itself. There are also package lifecycle/install scripts, which means installing a dependency can result in code being executed as part of the installation process.

That's a materially different trust boundary from downloading an official, versioned binary release and executing that artifact. With a binary I can pin something like:

redocly-cli-linux-x64@2.49.0

and ideally verify its checksum/signature. There is no npm dependency resolution or npm package installation taking place in my production environment.

So I'm not arguing:

"binary = no vulnerabilities"

I'm arguing:

"binary = I don't have to introduce an npm dependency tree into my production environment just to run this one CLI."

For my use case that distinction is important. I have quite a few dependencies already, and adding another npm dependency means accepting another set of transitive packages and their supply-chain risks. That's particularly undesirable for tooling that could otherwise be distributed as a self-contained executable.

The Docker image solves the Node runtime problem, which I appreciate, but it doesn't completely solve my underlying concern. It still gives me a container containing the npm application and its dependency tree. I'm specifically looking for a distribution mechanism where the production job consumes a known, immutable Redocly artifact, rather than installing/resolving JavaScript packages.

Ideally, I'd also be very happy with signed releases/checksums/SLSA provenance or an SBOM for the binary. That would let consumers verify exactly what they're executing.

So I don't expect the standalone binary to eliminate vulnerabilities in Redocly. The benefit I'm after is reducing the amount of third-party executable code and package-install machinery that my production environment has to trust.

Again, i really appreciate your time :)

[vadyvas]

The CLI is bundled, so the published package has no dependencies at all - you can confirm that here: https://www.npmjs.com/package/@redocly/cli?activeTab=dependencies

Every release is also signed with provenance, shown on the same page: https://www.npmjs.com/package/@redocly/cli

@8ball030 Does that address the dependency part of your concern?

[8ball030]

@vadyvas That is super helpful.
Thank you.
I would still prefer a binary, but it does go some way to making me feel a lot better!
So I have also just done a quick test as it piqued my interest;

Looks like you can get a binary using bun to compile.

With only one change to add in the name of the cli, it is pretty nice.

This binary then needs no node run time or anything at all to run and is only 77 mb. (I tested that as well)