Bump CLI

Help | Sign up

The Bump.sh CLI is used to interact with your API documentation or hubs hosted on Bump.sh. With any API definition of your choice (from Swagger, OpenAPI or AsyncAPI), it can help you to:

• Validate an API document before publishing it to your documentation
• Publish an API document to your Bump.sh documentation or hubs
• Compare two API documents to generate a human-readable diff from your API definitions

Under the hood, it uses the API of developers.bump.sh. And is built with the oclif framework in Typescript.

Table of contents

• Installation
• Usage
• Commands
• Development
• Contributing
• Versioning

Installation

The Bump.sh CLI is a node package currently distributed via NPM. This means you must have the Node v14+ interpreter installed on your computer or CI servers.

If you are looking to use Bump.sh in a continuous integration environment you might be interested by our Github Action.

> You can download a standalone package directly from the latest > GitHub release assets if you don’t use Node. {: .info}

Global installation

To install it globally, run the following command with NPM

npm install -g bump-cli

Or, with Yarn via

yarn global add bump-cli

Add Bump.sh to your node project

As our CLI is a node package, you can easily embed it into your project by adding the package to your package.json file, either with NPM

npm install --save-dev bump-cli

Or with Yarn via

yarn add --dev bump-cli

You can then use any Bump.sh commands with npx (same as npm exec)

npx bump --help

How should I do if I'm not using npm ?

Unfortunately, at the moment we only support the Node environment. However, you can download a standalone package directly from the latest Github release assets which you can run as a standalone binary. Or you can push your documentation using our API (advanced usage only).

Usage

To list all the available commands, just type bump in your command line environment.

$ bump --help
The Bump.sh CLI is used to interact with your API documentation hosted on Bump.sh by using the API of developers.bump.sh

VERSION
  bump-cli/2.8.0 linux-x64 node-v16.19.0

USAGE
  $ bump [COMMAND]

COMMANDS
  deploy   Create a new version of your documentation from the given file or URL.
  diff     Get a comparison diff with your documentation from the given file or URL.
  help     Display help for bump.
  overlay  Apply an OpenAPI specified overlay to your API definition.
  preview  Create a documentation preview from the given file or URL.

You can also get some help anytime by adding --help to any command. Example: bump deploy --help.

Prepare your Bump.sh account

While some commands don't need any API token (preview or diff) you will need an access key if you want to interact with your Bump.sh documentation.

Head over to your Documentation settings in the “CI deployment” section or your Account or Organization settings in the “API keys” section to fetch a personal token for later usage.

Commands

• bump deploy [FILE]
• bump diff [FILE]
• bump preview [FILE]
• bump overlay [DEFINITION_FILE] [OVERLAY_FILE]

bump deploy [FILE]

When you update your API, you also want its documentation to be up to date for your API users. This is what the deploy command is for.

bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN

> You can find your own my-documentation slug and $DOC_TOKEN api key from your documentation settings. {: .info}

You can also deploy a given API document to a different branch of your documentation with the --branch parameter. Please note the branch will be created if it doesn’t exist. More details about the branching feature are available on this dedicated help page. E.g. deploy the API document to the staging branch of the documentation:

bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging

Deploy a folder all at once

If you already have a hub in your Bump.sh account, you can automatically create documentation and deploy it into that hub by publishing a whole directory containing multiple API documents in a single command:

bump deploy dir/path/to/apis/ --auto-create --hub my-hub --token $HUB_TOKEN

> You can find your own my-hub slug and $HUB_TOKEN api key from your hub settings. {: .info}

Please note, by default, only files named {slug}-api.[format] are published. Where {slug} is a name for your API and [format] is either yaml or json. Adjust to your file naming convention using the `--filename-pattern