Bump CLI

Common errors

• Error: You are running Node.js x.y.z. Bump CLI requires Node.js version >= 20.0.0.

  cause The installed Node.js version on your system is older than the minimum required by `bump-cli`.
  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.

• Error: Missing required flag --token OR Error: Invalid API token provided.

  cause The `--token` flag was not provided during the command execution, or the provided API token is incorrect, expired, or lacks the necessary permissions.
  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.

• [ERROR] The document provided is not a valid OpenAPI/AsyncAPI specification.

  cause The API definition file (OpenAPI, AsyncAPI, Flower, or Arazzo) contains syntax errors or does not conform to its respective specification.
  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`).

• [ERROR] JSONPath evaluation failed: <some jsonpath expression>

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install bump-cli npm
• yarn add bump-cli yarn
• pnpm add bump-cli pnpm

Imports

• bump
  wrong:

  import { bump } from 'bump-cli'

  correct:

  bump [command]

  When globally installed (`npm install -g bump-cli`), the `bump` command is directly available in your shell's PATH.
• bump
  wrong:

  require('bump-cli')

  correct:

  npx bump [command]

  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.
• bump (programmatic)
  wrong:

  import { deploy } from 'bump-cli'; deploy(...) 

  correct:

  import { exec } from 'node:child_process'; exec('npx bump deploy ...', (err, stdout, stderr) => { /* ... */ });

  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.

Quickstart

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.

import { exec } from 'node:child_process';
import * as path from 'node:path';
import * as fs from 'node:fs';

const API_DEFINITION_FILE = 'openapi.yaml';
const BUMP_DOC_SLUG = process.env.BUMP_DOC_SLUG ?? 'my-api-documentation-test';
const BUMP_TOKEN = process.env.BUMP_TOKEN ?? ''; // Set BUMP_TOKEN environment variable

// Create a dummy OpenAPI file for demonstration
const openApiContent = `
openapi: 3.0.0
info:
  title: My Example API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: Returns a greeting
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Hello, World!
`;
fs.writeFileSync(API_DEFINITION_FILE, openApiContent.trim());

console.log(`Deploying ${API_DEFINITION_FILE} to Bump.sh documentation '${BUMP_DOC_SLUG}'...`);

const command = `npx bump deploy ${API_DEFINITION_FILE} --doc ${BUMP_DOC_SLUG} --token ${BUMP_TOKEN} --no-progress`;

exec(command, (error, stdout, stderr) => {
  if (error) {
    console.error(`exec error: ${error}`);
    console.error(`stderr: ${stderr}`);
    // Clean up the dummy file in case of error too
    fs.unlinkSync(API_DEFINITION_FILE);
    return;
  }
  console.log(`stdout: ${stdout}`);
  console.log('Deployment command finished. Check your Bump.sh dashboard!');
  
  // Clean up the dummy file
  fs.unlinkSync(API_DEFINITION_FILE);
});