OpenAPI CLI Installation Guide

December 10, 2025 ยท View on GitHub

This guide provides detailed installation instructions for the OpenAPI CLI tool across different platforms and methods.

Table of Contents

Homebrew (macOS/Linux)

The easiest way to install on macOS or Linux with Homebrew:

brew install openapi

To upgrade to the latest version:

brew upgrade openapi

Go Install

If you have Go installed, you can install directly:

go install github.com/speakeasy-api/openapi/cmd/openapi@latest

This installs the binary to your $GOPATH/bin directory (typically ~/go/bin).

Script-Based Installation

For quick installation without package managers, use our installation scripts.

Linux/macOS

curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

Or with wget:

wget -qO- https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

The script automatically detects if you have write permission to /usr/local/bin. If not, it installs to ~/.local/bin instead. No sudo required!

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 | iex

Or the long form:

Invoke-WebRequest -Uri https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 -UseBasicParsing | Invoke-Expression

Windows (Git Bash/MSYS2/Cygwin)

curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

Manual Installation

  1. Visit the latest release page
  2. Download the appropriate archive for your platform:
    • Linux (x86_64): openapi_Linux_x86_64.tar.gz
    • Linux (ARM64): openapi_Linux_arm64.tar.gz
    • macOS (x86_64): openapi_Darwin_x86_64.tar.gz
    • macOS (ARM64): openapi_Darwin_arm64.tar.gz
    • Windows (x86_64): openapi_Windows_x86_64.zip
    • Windows (ARM64): openapi_Windows_arm64.zip
  3. Extract the archive
  4. Move the openapi binary to a directory in your PATH

Example (Linux/macOS)

# Download (replace with actual version URL)
curl -LO https://github.com/speakeasy-api/openapi/releases/latest/download/openapi_Linux_x86_64.tar.gz

# Extract
tar -xzf openapi_Linux_x86_64.tar.gz

# Move to PATH
sudo mv openapi /usr/local/bin/

# Verify installation
openapi --help

Example (Windows - PowerShell)

# Download (replace with actual version URL)
Invoke-WebRequest -Uri "https://github.com/speakeasy-api/openapi/releases/latest/download/openapi_Windows_x86_64.zip" -OutFile "openapi.zip"

# Extract
Expand-Archive -Path openapi.zip -DestinationPath .

# Move to a directory in your PATH (example)
Move-Item openapi.exe $env:LOCALAPPDATA\Programs\

# Add to PATH if needed
$path = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$path;$env:LOCALAPPDATA\Programs", "User")

Custom Installation Options

Both installation scripts support custom configuration via environment variables.

Linux/macOS/Git Bash

Environment Variables:

  • OPENAPI_INSTALL_DIR - Installation directory (default: /usr/local/bin)
  • OPENAPI_VERSION - Specific version to install (default: latest)

Examples:

# Install to a custom directory
OPENAPI_INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

# Install a specific version
OPENAPI_VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

# Combine both options
OPENAPI_INSTALL_DIR=$HOME/bin OPENAPI_VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

Windows (PowerShell)

Environment Variables:

  • $env:OPENAPI_INSTALL_DIR - Installation directory (default: $env:LOCALAPPDATA\Programs\OpenAPI)
  • $env:OPENAPI_VERSION - Specific version to install (default: latest)

Examples:

# Install to a custom directory
$env:OPENAPI_INSTALL_DIR = "$env:USERPROFILE\.openapi"
iwr -useb https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 | iex

# Install a specific version
$env:OPENAPI_VERSION = "v1.0.0"
iwr -useb https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 | iex

# Combine both options
$env:OPENAPI_INSTALL_DIR = "$env:USERPROFILE\.openapi"
$env:OPENAPI_VERSION = "v1.0.0"
iwr -useb https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 | iex

Upgrading

Homebrew

brew upgrade openapi

Go Install

Simply reinstall to get the latest version:

go install github.com/speakeasy-api/openapi/cmd/openapi@latest

Script-Based Installation

The installation scripts always install the latest version by default, so simply run them again to upgrade.

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 | iex

Windows (Git Bash):

curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

The script will automatically replace the existing binary with the latest version.

Upgrade to Specific Version

To upgrade (or downgrade) to a specific version, use the version environment variable:

Linux/macOS/Git Bash:

OPENAPI_VERSION=v1.2.0 curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

Windows (PowerShell):

$env:OPENAPI_VERSION = "v1.2.0"
iwr -useb https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 | iex

Manual Upgrade

If you installed manually, follow the same manual installation steps to download and replace the binary with the newer version.

Checking Your Current Version

To see which version you currently have installed:

openapi --version

Troubleshooting

Command Not Found After Installation

If you get "command not found" after installation, the installation directory may not be in your PATH.

Linux/macOS:

Add the installation directory to your PATH by adding this line to your ~/.bashrc, ~/.zshrc, or equivalent:

export PATH="$PATH:/usr/local/bin"

Or for custom installation directories:

export PATH="$PATH:$HOME/.local/bin"

Then reload your shell configuration:

source ~/.bashrc  # or ~/.zshrc

Windows:

The PowerShell script automatically adds the installation directory to your PATH. If it's still not working:

  1. Restart your terminal
  2. Or run refreshenv (if you have Chocolatey installed)
  3. Or manually add the directory to your PATH in System Environment Variables

Permission Denied (Linux/macOS)

The installation script automatically detects if you have write permission to /usr/local/bin and falls back to ~/.local/bin if needed. However, if you still encounter permission issues:

Option 1: Explicitly set a user-writable directory

OPENAPI_INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

Option 2: Run with sudo (download and review first)

# Download script first, review it, then run with sudo
curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh

If installed to ~/.local/bin, ensure it's in your PATH (see Command Not Found).

Windows Git Bash Issues

If you're using Git Bash on Windows and encounter issues:

  1. Ensure you have unzip installed (may need to install via Git for Windows options)
  2. Or use the PowerShell script instead for a smoother experience

Version-Specific Installation

To install a specific version, use the version environment variable:

# Linux/macOS
OPENAPI_VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

# Windows (PowerShell)
$env:OPENAPI_VERSION = "v1.0.0"
iwr -useb https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 | iex

Verifying Installation

After installation, verify it worked:

openapi --help

You should see the help output for the OpenAPI CLI tool.

Uninstalling

Homebrew:

brew uninstall openapi

Go Install:

rm $(which openapi)

Script Installation (Linux/macOS):

sudo rm /usr/local/bin/openapi
# Or if you used a custom directory:
rm $HOME/.local/bin/openapi

Script Installation (Windows - PowerShell):

Remove-Item "$env:LOCALAPPDATA\Programs\OpenAPI\openapi.exe"

Getting Help

If you encounter issues not covered here:

  1. Check the GitHub Issues
  2. Open a new issue with details about your platform and the error
  3. Join our Slack community for support