{"id":16957,"library":"bump-cli","title":"Bump CLI","description":"The Bump CLI is a command-line interface tool designed to interact with the Bump.sh platform, enabling developers to manage their API documentation, hubs, and workflows directly from their development environments. It supports popular API description formats such as OpenAPI (v2.0, v3.x, and partially v3.2), Swagger, and AsyncAPI for documentation, as well as Flower and Arazzo for API workflows. The current stable version is 2.10.0, with releases occurring frequently, often on a monthly or bi-monthly basis, incorporating new features and bug fixes. Key functionalities include validating API documents, publishing them to Bump.sh documentation or hubs, generating human-readable diffs between API definitions, applying overlays, and deploying workflow documents to Managed Control Plane (MCP) servers. The CLI is built with the `oclif` framework in TypeScript and primarily interfaces with the `developers.bump.sh` API.","status":"active","version":"2.10.0","language":"javascript","source_language":"en","source_url":"https://github.com/bump-sh/cli","tags":["javascript","api","documentation","openapi","asyncapi","bump","cli","typescript"],"install":[{"cmd":"npm install bump-cli","lang":"bash","label":"npm"},{"cmd":"yarn add bump-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add bump-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"When globally installed (`npm install -g bump-cli`), the `bump` command is directly available in your shell's PATH.","wrong":"import { bump } from 'bump-cli'","symbol":"bump","correct":"bump [command]"},{"note":"When installed as a local dev dependency (`npm install --save-dev bump-cli`), it should be invoked using `npx` (or `npm exec`) from your project root.","wrong":"require('bump-cli')","symbol":"bump","correct":"npx bump [command]"},{"note":"The CLI is primarily designed for shell execution. Programmatic invocation usually involves spawning a child process rather than importing specific functions, as its internal structure is optimized for CLI execution.","wrong":"import { deploy } from 'bump-cli'; deploy(...) ","symbol":"bump (programmatic)","correct":"import { exec } from 'node:child_process'; exec('npx bump deploy ...', (err, stdout, stderr) => { /* ... */ });"}],"quickstart":{"code":"import { exec } from 'node:child_process';\nimport * as path from 'node:path';\nimport * as fs from 'node:fs';\n\nconst API_DEFINITION_FILE = 'openapi.yaml';\nconst BUMP_DOC_SLUG = process.env.BUMP_DOC_SLUG ?? 'my-api-documentation-test';\nconst BUMP_TOKEN = process.env.BUMP_TOKEN ?? ''; // Set BUMP_TOKEN environment variable\n\n// Create a dummy OpenAPI file for demonstration\nconst openApiContent = `\nopenapi: 3.0.0\ninfo:\n  title: My Example API\n  version: 1.0.0\npaths:\n  /hello:\n    get:\n      summary: Returns a greeting\n      responses:\n        '200':\n          description: A successful response\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  message:\n                    type: string\n                    example: Hello, World!\n`;\nfs.writeFileSync(API_DEFINITION_FILE, openApiContent.trim());\n\nconsole.log(`Deploying ${API_DEFINITION_FILE} to Bump.sh documentation '${BUMP_DOC_SLUG}'...`);\n\nconst command = `npx bump deploy ${API_DEFINITION_FILE} --doc ${BUMP_DOC_SLUG} --token ${BUMP_TOKEN} --no-progress`;\n\nexec(command, (error, stdout, stderr) => {\n  if (error) {\n    console.error(`exec error: ${error}`);\n    console.error(`stderr: ${stderr}`);\n    // Clean up the dummy file in case of error too\n    fs.unlinkSync(API_DEFINITION_FILE);\n    return;\n  }\n  console.log(`stdout: ${stdout}`);\n  console.log('Deployment command finished. Check your Bump.sh dashboard!');\n  \n  // Clean up the dummy file\n  fs.unlinkSync(API_DEFINITION_FILE);\n});","lang":"typescript","description":"This quickstart demonstrates how to programmatically deploy an OpenAPI definition to Bump.sh using the `bump-cli` via `npx` and environment variables for authentication. It creates a temporary OpenAPI file, deploys it, and then cleans up."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.0.0 or later. Use a Node Version Manager (NVM) for easy switching and management of Node.js versions.","message":"Node.js Version Requirement: `bump-cli` now requires Node.js version 20.0.0 or higher. Older Node.js versions are no longer supported and will prevent the CLI from running.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Execute `bump-cli` commands from your shell using `npx bump [command]` (for local installation) or `bump [command]` (for global installation). For programmatic execution, use `node:child_process` to spawn the command.","message":"CLI Tool Usage: `bump-cli` is primarily a command-line interface tool and is not intended for direct programmatic import as a library. Attempting `import { ... } from 'bump-cli'` or `require('bump-cli')` will not work as expected for its core functionalities.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Consult the Bump.sh documentation for specific limitations on OpenAPI 3.2 features. Test your OpenAPI 3.2 documents thoroughly after deployment and report any issues encountered to ensure full compatibility in future releases.","message":"OpenAPI 3.2 Partial Support: While `bump-cli` supports deployment of OpenAPI 3.2 documents, this support is currently partial. Certain advanced or newly introduced OpenAPI 3.2 features might not be fully rendered or processed as expected.","severity":"gotcha","affected_versions":">=2.9.9"},{"fix":"Review any existing overlay files that use JSON paths with the `overlay` command to ensure they conform to RFC 9535 standards. Test overlays thoroughly after updating to version 2.9.11 or newer to avoid unexpected behavior.","message":"JSON Path Compliance (RFC 9535): The `overlay` command's JSON Path parsing has been updated to be more compliant with RFC 9535. This is generally a fix, but previously working non-standard JSON paths in overlay files might behave differently or break.","severity":"breaking","affected_versions":">=2.9.11"},{"fix":"Refer to the latest Bump.sh documentation regarding MCP server deployments for up-to-date information on supported features and any known limitations. Provide feedback to Bump.sh to help mature the feature.","message":"MCP Server Deployment Feature Status: The deployment of workflow documents to Managed Control Plane (MCP) servers (using `--mcp-server`) was initially in a beta or \"in creation\" state. While it now supports Arazzo documents, users should be aware that this feature is still actively evolving and may have limitations.","severity":"gotcha","affected_versions":">=2.9.12"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 20.0.0 or later. Tools like `nvm install 20 && nvm use 20` or `npm install -g n && n 20` can help manage Node.js versions easily.","cause":"The installed Node.js version on your system is older than the minimum required by `bump-cli`.","error":"Error: You are running Node.js x.y.z. Bump CLI requires Node.js version >= 20.0.0."},{"fix":"Ensure you pass a valid Bump.sh API token using `--token $BUMP_TOKEN` or by setting the `BUMP_TOKEN` environment variable. Generate a new token if necessary from your Bump.sh account settings.","cause":"The `--token` flag was not provided during the command execution, or the provided API token is incorrect, expired, or lacks the necessary permissions.","error":"Error: Missing required flag --token OR Error: Invalid API token provided."},{"fix":"Validate your API definition file locally using a linter (e.g., `spectral lint` for OpenAPI/AsyncAPI) or a schema validator before attempting to deploy. Check for common issues like incorrect YAML/JSON syntax, missing required fields, or invalid schema references (`$refs`).","cause":"The API definition file (OpenAPI, AsyncAPI, Flower, or Arazzo) contains syntax errors or does not conform to its respective specification.","error":"[ERROR] The document provided is not a valid OpenAPI/AsyncAPI specification."},{"fix":"Review the JSON Path expression in your overlay file. Ensure it adheres to RFC 9535 standards for JSON Path. Test the overlay locally using the `bump overlay` command before deployment to verify its correctness.","cause":"An incorrect or unsupported JSON Path expression was used in an overlay file, especially after the `2.9.11` update which standardized JSON Path compliance with RFC 9535.","error":"[ERROR] JSONPath evaluation failed: <some jsonpath expression>"}],"ecosystem":"npm","meta_description":null}