Bump CLI

Bump CLI is the command-line companion to Bump.sh, letting teams push OpenAPI, Swagger, and AsyncAPI documents (plus Arazzo and Flower workflow specs) straight from a repo or CI job into hosted, versioned documentation. It handles the mechanics that would otherwise require hand-rolled scripts against Bump.sh’s workspace API: resolving $ref includes across multiple files, validating a document against the right spec version, generating a human-readable diff between two revisions, and applying OpenAPI overlays before publishing.

Built on the oclif CLI framework, it ships five focused commands (deploy, diff, preview, overlay, help) that can run unauthenticated for quick previews and diffs, or authenticated against a documentation, hub, or MCP server token for real deployments. It also bulk-deploys an entire directory of API definitions into a hub in one invocation, using a configurable filename pattern to infer each file’s documentation slug.

What You Get

• A deploy command that creates a new documentation version from a local file, a URL, or an entire directory of API definitions deployed to a hub at once
• A diff command that produces a human-readable, breaking-change-aware comparison between two API documents, with an option to fail CI on breaking changes
• A preview command that spins up a temporary, shareable documentation URL (with an optional --live mode that re-renders on every file save)
• An overlay command implementing the OpenAPI Overlay Specification to apply non-destructive layered changes to a definition before diffing or deploying
• Multi-format support in one tool: OpenAPI 2.0-3.1, AsyncAPI 2.x, and the newer Arazzo and Flower workflow specifications, including automatic $ref resolution across files

Common Use Cases

• Publishing updated API documentation to Bump.sh automatically from a GitHub Actions or other CI workflow on every merge to main
• Failing a pull request’s CI check when bump diff --fail-on-breaking detects a breaking API change before it ships
• Sharing a temporary, unauthenticated preview link of an in-progress OpenAPI file with a reviewer via bump preview
• Bulk-publishing a monorepo’s worth of per-service OpenAPI files into a single Bump.sh hub using a shared filename convention
• Applying an OpenAPI overlay to redact or adjust portions of a spec (e.g. internal-only endpoints) before it is deployed or diffed

Under The Hood

Architecture Bump CLI is a clean three-layer design: thin commands/ classes (oclif Command subclasses for deploy, diff, preview, overlay) parse flags/args and delegate immediately to core/ classes (Deploy, WorkflowDeploy, DefinitionDirectory, Overlay) that hold the actual orchestration logic, which in turn call a dedicated api/ layer (BumpApi, an axios client with a response interceptor that normalizes failures into a typed APIError). Binding all of it together is definition.ts’s API class, the central domain model: it loads a file or URL through @apidevtools/json-schema-ref-parser to resolve $ref includes, uses type-guard methods (isOpenAPI, isAsyncAPI, isArazzo, isFlower, isOpenAPIOverlay) to classify the parsed document against a discriminated union, and validates it against bundled per-version JSON Schemas. Every command (deploy, diff, preview, overlay) funnels through this same API.load() path, so it is the one abstraction whose correctness the rest of the codebase depends on.

Tech Stack TypeScript on Node 20+, built on oclif v4 (@oclif/core, @oclif/plugin-help, @oclif/plugin-warn-if-update-available) for command/flag parsing and update nudges. HTTP calls go through axios; YAML parsing and comment-preserving re-serialization use @stoplight/yaml; $ref dereferencing uses @apidevtools/json-schema-ref-parser; overlay merging uses mergician and JSONPath targeting via jsonpathly; interactive prompts use @clack/prompts; terminal styling uses chalk. Spec validation schemas for OpenAPI/Arazzo/Flower are vendored as their own sub-modules, plus @asyncapi/specs for AsyncAPI. The package is distributed on npm but also packaged via oclif pack tarballs into standalone binaries for non-Node users, with releases automated through np and GitHub Actions.

Code Quality Tests use mocha and chai, with nock mocking all Bump.sh API calls and sinon for stubbing, run through @oclif/test’s runCommand helper so each command is exercised close to end-to-end; coverage is measured via nyc. Every core command (deploy, diff, preview, overlay) has a dedicated test file, plus separate unit tests for the definition.ts model and the API client. Linting runs oclif’s shared ESLint/TypeScript config with Prettier integration, wired into npm test via a posttest script so lint failures fail CI (checks.yml) the same as test failures. Error handling is explicit and typed rather than swallowed: a custom APIError wraps axios failures, oclif’s CLIError surfaces user-facing messages, and definition.ts raises a dedicated UnsupportedFormat error for unrecognized specs.

What Makes It Unique Most API-doc CLIs target a single spec format; Bump CLI’s API class treats OpenAPI, AsyncAPI, Arazzo, and Flower as a single discriminated-union domain model with shared $ref resolution, overlay application, and diffing, so one command set covers both classic REST/event-driven API docs and newer MCP-server workflow definitions. The --live preview mode and directory-wide hub deploy with configurable filename-pattern slug extraction are practical conveniences layered on top of that shared core rather than one-off scripts.