{"id":13902919,"url":"https://github.com/bump-sh/cli","last_synced_at":"2026-01-30T12:03:30.093Z","repository":{"id":36954141,"uuid":"353317141","full_name":"bump-sh/cli","owner":"bump-sh","description":"Bump.sh CLI - Deploy your OpenAPI \u0026 AsyncAPI documentations from your CI","archived":false,"fork":false,"pushed_at":"2026-01-14T09:03:33.000Z","size":3012,"stargazers_count":64,"open_issues_count":15,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-25T07:57:52.996Z","etag":null,"topics":["api-specification","asyncapi","asyncapi-specification","cli","openapi","openapi-specification","openapi2","openapi3"],"latest_commit_sha":null,"homepage":"https://bump.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bump-sh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-03-31T10:29:18.000Z","updated_at":"2026-01-13T15:59:39.000Z","dependencies_parsed_at":"2024-02-02T13:54:50.922Z","dependency_job_id":"73b6d037-09a0-4358-9343-1254743aeba3","html_url":"https://github.com/bump-sh/cli","commit_stats":{"total_commits":347,"total_committers":8,"mean_commits":43.375,"dds":0.4553314121037464,"last_synced_commit":"54b09f2105d22ee7a05ef064dcde1723cb33940e"},"previous_names":["bump-sh/bump-node-cli"],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/bump-sh/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bump-sh","download_url":"https://codeload.github.com/bump-sh/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bump-sh%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28912237,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T11:55:24.701Z","status":"ssl_error","status_checked_at":"2026-01-30T11:54:13.194Z","response_time":66,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-specification","asyncapi","asyncapi-specification","cli","openapi","openapi-specification","openapi2","openapi3"],"created_at":"2024-08-06T22:01:29.843Z","updated_at":"2026-01-30T12:03:30.085Z","avatar_url":"https://github.com/bump-sh.png","language":"TypeScript","readme":"# Bump CLI\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"20%\" src=\"https://bump.sh/icon-default-maskable-large.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://docs.bump.sh/help\"\u003eHelp\u003c/a\u003e |\n  \u003ca href=\"https://bump.sh/users/sign_up\"\u003eSign up\u003c/a\u003e\n\u003c/p\u003e\n\nThe Bump.sh CLI is used to interact with API documentation and hubs hosted on Bump.sh from your choice of popular API description formats: OpenAPI, Swagger, or AsyncAPI.\n\nUsing [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (v3.x and v2.0) or [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) (2.x), you can do any of the following:\n\n- Validate an API document before publishing to your documentation.\n- Publish an API document to your Bump.sh documentation or hubs.\n- Compare two API documents to generate a human-readable diff from your API definition.\nUnder the hood, it uses the API of [developers.bump.sh](https://developers.bump.sh). And is built with the [`oclif`](https://oclif.io) framework in Typescript.\n\n[![Version](https://img.shields.io/npm/v/bump-cli.svg)](https://npmjs.org/package/bump-cli)\n[![Tests](https://github.com/bump-sh/cli/actions/workflows/checks.yml/badge.svg)](https://github.com/bump-sh/cli/actions/workflows/checks.yml)\n[![License](https://img.shields.io/npm/l/bump-cli.svg)](https://github.com/bump-sh/cli/blob/master/package.json)\n\n## Table of contents\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [Commands](#commands)\n* [Development](#development)\n* [Contributing](#contributing)\n* [Versioning](#versioning)\n\n## Installation\n\nThe Bump.sh CLI is a node package currently distributed via NPM. This means you must have the Node v20+ interpreter installed on your computer or CI servers.\n\n_If you are looking to use Bump.sh in a continuous integration environment you might be interested by [our Github Action](https://github.com/marketplace/actions/bump-sh-api-documentation-changelog)._\n\n\u003e You can download a standalone package directly from the latest\n\u003e Github release assets if you don’t use Node.\n{: .info}\n\n### Global installation\n\nTo install it globally, run the following command with NPM:\n\n```shell\nnpm install -g bump-cli\n```\n\nOr, with Yarn via:\n\n```shell\nyarn global add bump-cli\n```\n\n### Add Bump.sh to your Node project\n\nAs our CLI is a node package, you can easily embed it to your project by adding the package to your `package.json` file, either with NPM:\n\n```shell\nnpm install --save-dev bump-cli\n```\n\nOr with Yarn via:\n\n```shell\nyarn add --dev bump-cli\n```\n\nYou can then use any Bump.sh commands with `npx` (same as `npm exec`):\n\n```shell\nnpx bump --help\n```\n\n### Can I install Bump.sh CLI without using NodeJS?\n\nUnfortunately, at the moment we only support the Node environment. However, you can download a standalone package directly from the [latest Github release](https://github.com/bump-sh/cli/releases) assets which you can run as a standalone binary. Or you can push your documentation using [our API](https://developers.bump.sh/) (advanced usage only).\n\n## Usage\n\nTo list all the available commands, just type `bump` in your command line environment.\n\n```shell\n$ bump --help\nThe Bump.sh CLI is used to interact with your API documentation hosted on Bump.sh by using the API of developers.bump.sh\n\nVERSION\n  bump-cli/x.y.z linux-x64 node-v20+\n\nUSAGE\n  $ bump [COMMAND]\n\nCOMMANDS\n  deploy   Create a new version of your documentation from the given file or URL.\n  diff     Get a comparison diff with your documentation from the given file or URL.\n  help     Display help for bump.\n  overlay  Apply an OpenAPI specified overlay to your API definition.\n  preview  Create a documentation preview from the given file or URL.\n```\n\n You can also get some help anytime by adding `--help` to any command. Example: `bump deploy --help`.\n\n### Prepare your Bump.sh account\n\nWhile 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.\n\nHead 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.\n\n## Commands\n\n* [`bump deploy [FILE]`](#the-deploy-command)\n* [`bump diff [FILE]`](#the-diff-command)\n* [`bump preview [FILE]`](#the-preview-command)\n* [`bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`](#the-overlay-command)\n\n### The `deploy` command\n\nWhen an API is updated, the documentation should be updated at the same time. This is what the deploy command is for.\n\n```shell\nbump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN\n```\n\n\u003e You can find your own `my-documentation` slug and `$DOC_TOKEN` api key from your [documentation settings](https://bump.sh/docs).\n{: .info}\n\nYou can also deploy a given API document to a different branch of your documentation with the `--branch \u003cbranch-name\u003e` 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](https://docs.bump.sh/help/branching). E.g. deploy the API document to the `staging` branch of the documentation:\n\n```shell\nbump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging\n```\n\n#### Deploy a folder all at once\n\nIf you already have a hub in your [Bump.sh](https://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:\n\n```shell\nbump deploy dir/path/to/apis/ --auto-create --hub my-hub --token $HUB_TOKEN\n```\n\n\u003e You can find your own `my-hub` slug and `$HUB_TOKEN` api key from your [hub settings](https://bump.sh/hubs).\n{: .info}\n\nPlease 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 \u003cpattern\u003e` option.\n\nNote that it _can_ include `*` wildcard special character, but **must** include the `{slug}` filter to extract your documentation’s slug from the filename. The pattern can also have any other optional fixed characters.\n\nHere’s a practical example. Let's assume that you have the following files in your `path/to/apis/` directory:\n\n```\npath/to/apis\n└─ private-api-users-service.json\n└─ partner-api-payments-service.yml\n└─ public-api-contracts-service.yml\n└─ data.json\n└─ README.md\n```\n\nIn order to deploy the 3 services API definition files from this folder (`private-api-users-service.json`, `partner-api-payments-service.yml` and `public-api-contracts-service.yml`), you can execute the following command:\n\n```\nbump deploy path/to/apis/ --hub my-hub --filename-pattern '*-api-{slug}-service'\n```\n\n#### Validate an API document\n\nSimulate your API document's deployment to ensure it is valid by adding the `--dry-run` flag to the `deploy` command. It is handy in a Continuous Integration environment running a test deployment outside your main branch:\n\n```shell\nbump deploy path/to/api-document.yml --dry-run --doc my-documentation --token $DOC_TOKEN\n```\n\nPlease check `bump deploy --help` for more usage details.\n\n### The `diff` command\n\nUsing the `diff` command can help to spot differences between the local API\ndocument and the latest deployed version.\n\n#### Public API diffs\n\nFrom any two API documents or URLs, you can retrieve a comprehensive changelog\nof what has changed between them.\n\n```shell\n$ bump diff path/to/your/file.yml path/to/your/second_file.yml\n* Comparing the two given definition files... done\nModified: GET /consommations\n  Response modified: 200\n    [Breaking] Body attribute modified: energie\n```\n\nBy default the command will always exit with a successful return code. If you\nwant to use this command in a CI environment and want the command to fail **in\ncase of a breaking change**, you will need to add the `--fail-on-breaking` flag\nto your diff command.\n\nBy default if the environment variable `CI=1` is present (in most continuous\nintegration environment), the flag will be enabled. In that case you can disable\nthe failures with `--no-fail-on-breaking` flag.\n\nYou can also test this feature in our dedicated web application at\n\u003chttps://api-diff.io/\u003e.\n\n#### GitHub Integration\n\nIf you want to receive automatic `bump diff` results on Github Pull Requests you\nmight be interested by [our Github\nAction](https://github.com/marketplace/actions/bump-sh-api-documentation-changelog#deploy-documentation--diff-on-pull-requests)\nwhich has support for the diff command.\n\n#### Authenticated diffs related to your Bump.sh documentation\n\nFrom an existing Bump.sh documentation, the `diff` command will retrieve a\ncomparison changelog between your latest published documentation and the given\nfile or URL:\n\n```shell\nbump diff path/to/your/file.yml --doc my-documentation --token $DOC_TOKEN\n```\n\nIf you want to compare two unpublished versions of your API document, the `diff` command can retrieve a comparison changelog between two given file or URL, “as simple as `git diff`”:\n\n```shell\nbump diff path/to/your/file.yml path/to/your/next-file.yml --doc my-documentation --token $DOC_TOKEN\n```\n\nPlease check `bump diff --help` for full usage details.\n\n#### Diffs with overlayed source files\n\nThe `bump diff` command also supports [overlays](#the-overlay-command). This means you can pass the `--overlay my-overlay-file.yml` flag to the command and it will apply the overlay on both files **before** running the diff. E.g.:\n\n```shell\nbump diff --overlay my-overlay.yml path/to/your/file.yml path/to/your/next-file.yml\n```\n\n### The `preview` command\n\nWhen writing documentation, you might want to preview how it renders on Bump.sh.\nThis is precisely the goal of the `preview` command: it will create temporary\ndocumentation with a unique URL, which will be available for a short period (30\nminutes).\n\nUsage from a local OpenAPI or AsyncAPI document:\n\n```shell\nbump preview path/to/file.json\n```\n\nYou can also preview a document available via a URL:\n\n```shell\nbump preview https://developers.bump.sh/source.yaml\n```\n\n#### Live preview\n\nBy using the `--live` flag you can stay focused on API design (OpenAPI or AsyncAPI file) while seeing a continuously updated preview each time you save your API document.\n\n- Launch the live preview command in your terminal\n\n```shell\nbump preview --live --open api-document.yaml\n```\n\n- Edit your `api-document.yaml` file in your favorite text editor.\n- Watch the live preview being updated each time you save your file.\n- The additional `--open` flag helps to automatically open the preview URL in your browser.\n\n\u003e You can create as many previews as you like without being authenticated. This is a **free and unlimited service**.\n{: .info}\n\nPlease check `bump preview --help` for more usage details\n\n### The `overlay` command\n\nThe [Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) from the OpenAPI Initiative makes it possible to modify the content of an API definition by adding a layer on top of it. That layer helps adding, removing or changing some or all of the content of the original definition. \n\nThe `bump overlay` command takes an original API document, applies the changes from the overlay document, and outputs a modified version. No changes are made directly to the original document.\n\n```shell\nbump overlay api-document.yaml overlay.yaml\n```\n\nTo redirect the output of the command to a new file you can run:\n\n```shell\nbump overlay api-document.yaml overlay.yaml \u003e modified-api-document.yaml\n```\n\nYou can also apply the overlay using the [`deploy` command](#the-deploy-command) with the `--overlay` flag:\n\n```shell\nbump deploy api-document.yaml --doc my-doc --token my-token --overlay overlay.yaml\n```\n\nIf there are multiple overlays which need to be applied, the `--overlay` can be passed multiple times.\n\n```shell\nbump deploy api-document.yaml \\\n  --doc my-doc \\\n  --token my-token \\\n  --overlay overlay1.yaml \\\n  --overlay overlay2.yaml\n```\n\n## Development\n\nMake sure to have Node.js (At least v20) installed on your machine.\n\n- Install node dependencies with\n\n  ```shell\n  npm install\n  ```\n\n- Compile the Typescript code\n\n\n  ```shell\n  npm run build\n  npm run clean # Remove build artifacts\n  ```\n\n- Format the codebase to comply with the linter rules\n\n  ```shell\n  npm run fmt\n  ```\n\n- Run the test suites\n\n  ```shell\n  npm run test\n  npm run test-coverage # Run tests with coverage\n  ```\n\n### Use package in local environment\n\nYou can run the package by executing the file `bin/run.js` locally:\n\n  ```shell\n  bin/run.js\n  ```\n\nFor example to generate a preview:\n\n  ```shell\n  ./bin/run.js preview path/to/file.json\n  \u003e Your preview is visible at: https://bump.sh/preview/42\n  ```\n\nPlease note that even if CLI is running locally, by default requests are sent to [Bump.sh API](https://developers.bump.sh/).\n\nIf you have a local version of the Bump.sh API, you can run CLI 100% in local environment\nby setting the environment variable `BUMP_HOST`:\n\n  ```shell\n  BUMP_HOST=\"http://localhost:3000\" ./bin/run.js preview path/to/file.json\n  \u003e Your preview is visible at: http://localhost:3000/preview/42\n  ```\n\n## License\n\nThe Bump CLI project is released under the [MIT License](http://opensource.org/licenses/MIT).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at \u003chttps://github.com/bump-sh/cli\u003e. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## Code of Conduct\n\nEveryone interacting in the Bump-CLI project codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/bump-sh/.github/blob/main/CODE_OF_CONDUCT.md).\n\n## Thanks\n\n- [Lorna Mitchel](https://github.com/lornajane/) for [openapi-overlay-js](https://github.com/lornajane/openapi-overlays-js).\n- [Rico](https://github.com/rstacruz) for transferring the ownership of the `bump-cli` package name.\n","funding_links":[],"categories":["cli","TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbump-sh%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbump-sh%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbump-sh%2Fcli/lists"}