SwaggerHub CLI

0.11.0 · active · verified Wed Apr 22

The SwaggerHub CLI is a command-line interface tool designed to enable automation and streamline workflows around SwaggerHub. It allows teams to integrate API lifecycle management directly into their CI/CD pipelines, supporting operations such as creating new APIs, updating existing API versions, and managing API states (e.g., marking versions as published or default). The current stable version is `0.11.0`. The package exhibits an active release cadence, with minor versions frequently introducing new features and improvements, often leveraging the `oclif` framework. Its primary differentiator is providing robust command-line access to SwaggerHub functionalities, making it ideal for programmatic API management and governance.

Common errors

```
FetchError: request to https://... failed, reason: self signed certificate
```
cause Node.js refusing to trust a self-signed or privately signed SSL certificate from a SwaggerHub On-Premise instance.

fix Specify custom trusted certificates using the `NODE_EXTRA_CA_CERTS` environment variable. Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/certs.pem`.
```
Error: Missing SwaggerHub API Key
```
cause The `SWAGGERHUB_API_KEY` environment variable is not set, or the API Key was not provided during `swaggerhub configure`.

fix Set the `SWAGGERHUB_API_KEY` environment variable or run `swaggerhub configure` and provide your API Key from SwaggerHub user settings.
```
Error: Command '...' not found.
```
cause Attempting to use a command that does not exist, is misspelled, or is part of a different namespace.

fix Verify the command name and its namespace (e.g., `api:validate` instead of `validate`), and consult the `swaggerhub help` output for available commands.

Warnings

breaking Node.js 12.x and 14.x are no longer supported since v0.7.0. The CLI now requires Node.js 16.x or newer.
Fix: Upgrade your Node.js runtime to version 16.x or later. The current latest versions (0.11.x) require Node.js `^20.17.0 || >=22.9.0`.
breaking The minimum required Node.js version has been progressively updated. As of v0.11.0, Node.js `^20.17.0 || >=22.9.0` is required. Older Node.js versions (e.g., 16.x, 18.x) may no longer work.
Fix: Ensure your Node.js environment meets the specified engine requirements. Update to Node.js 20.17.0 or 22.9.0 and above.
gotcha For SwaggerHub On-Premise instances using self-signed or privately signed SSL certificates, Node.js will reject the connection by default, leading to 'self signed certificate' errors. This requires additional configuration.
Fix: Set the `NODE_EXTRA_CA_CERTS` environment variable to the path of a `.pem` file containing your custom trusted CA certificates. For example: `export NODE_EXTRA_CA_CERTS=/path/to/your/certs.pem`.
gotcha The `SWAGGERHUB_API_KEY` is a sensitive credential. Ensure it is kept secure and avoid committing it directly into version control. Use environment variables or secure secrets management for CI/CD.
Fix: Store `SWAGGERHUB_API_KEY` in environment variables or use a secret management system (e.g., GitHub Actions Secrets, Kubernetes Secrets) in automated workflows.
deprecated The specific endpoint used by the `api:validate` command received updates around v0.6.5, which included a fallback to an older validation endpoint. While a fix was implemented, relying on specific endpoint behavior might be brittle.
Fix: Always use the latest version of `swaggerhub-cli` to ensure compatibility with SwaggerHub API endpoints and validation logic. Report any unexpected validation issues to the maintainers.

Install

npm install swaggerhub-cli npm
yarn add swaggerhub-cli yarn
pnpm add swaggerhub-cli pnpm

Imports

swaggerhub
wrong:
```
node swaggerhub
```
correct:
```
swaggerhub <command> [args]
```
The `swaggerhub` command is typically installed globally and invoked directly from the terminal.
swaggerhub configure
```
swaggerhub configure
```
Used for initial setup, interactively prompting for SwaggerHub URL and API Key. Values can also be set via environment variables.
swaggerhub api:validate
wrong:
```
swaggerhub validate-api <owner>/<apiName>/<version>
```
correct:
```
swaggerhub api:validate <owner>/<apiName>/<version>
```
Validates an API definition against SwaggerHub's rules. Note the `api:` namespace for API-related commands.
SWAGGERHUB_API_KEY
```
export SWAGGERHUB_API_KEY="<your-key>"
```
Environment variable for authentication. Takes precedence over `swaggerhub configure` settings. Crucial for CI/CD.

Quickstart

Installs the CLI globally, demonstrates interactive configuration or environment variable setup, and runs basic commands like listing APIs and validating a local spec.

npm i -g swaggerhub-cli

# Configure interactively (alternative: set environment variables)
swaggerhub configure
# ? SwaggerHub URL: https://api.swaggerhub.com
# ? API Key: <your-api-key>

# Or configure using environment variables for non-interactive setups (e.g., CI/CD)
# export SWAGGERHUB_API_KEY="shub-api-key-123"
# export SWAGGERHUB_URL="https://api.swaggerhub.com"

# List all APIs accessible with the configured key
swaggerhub api:list

# Example: Validate a local API definition file
# Create a dummy OpenAPI spec file for validation
echo 'openapi: 3.0.0\ninfo:\n  title: My Test API\n  version: 1.0.0\npaths: {}\n' > my-api.yaml
swaggerhub api:validate:local my-api.yaml

# Clean up
rm my-api.yaml

view raw JSON →