CLI overview

Overview

The speakeasy CLI manages platform resources directly from the terminal. Use it to authenticate, stage OpenAPI documents and Functions for deployment, push and monitor deployments, install MCP servers in AI agents, and keep the CLI itself up to date.

Installation

Install the speakeasy CLI with one of the following methods:

curl -fsSL https://ai.speakeasy.com/cli.sh | bash

After installation, run the following command to verify that the CLI is installed correctly:

speakeasy --version

The CLI was previously called gram. The gram command still works but prints a deprecation warning. The speakeasy-api/tap/gram Homebrew formula is deprecated in favor of speakeasy-api/tap/cli.

Its GRAM_* environment variables are now SPEAKEASY_AI_*, for example SPEAKEASY_AI_API_KEY. The old names still work and print a deprecation warning. The profile moved from ~/.gram/profile.json to ~/.config/speakeasy-ai/profile.json, and the CLI copies existing profiles across the first time it saves one.

Name clash with the SDK generator

The Speakeasy SDK generator CLI also installs a binary called speakeasy. If speakeasy --version shows the SDK generator, reinstall with INSTALL_DIR="$HOME/.local/bin" set for the install script, or install with Homebrew, which declares the conflict.

Then authenticate:

speakeasy auth

Authentication

Use speakeasy auth to bootstrap an account:

speakeasy auth

Then, inspect the current profile:

speakeasy whoami

The first time speakeasy auth runs, it creates and saves a producer-scoped API key in the dashboard.

Available commands

- auth - install - push - stage - stage function - stage openapi - status - update - whoami

The speakeasy functions commands (init, build, dev, push, and stage) scaffold, run, and deploy Functions projects. See Build and deploy.

Global CLI options

The following global options are available across CLI commands.

`api-key`

Use api-key to provide an API key (which must have the producer scope):

speakeasy push --api-key MY_API_KEY [command options]

When this option is not provided, the CLI falls back to using the following values, in this order:

The SPEAKEASY_AI_API_KEY environment variable
The secret field of the current profile in ~/.config/speakeasy-ai/profile.json

`project`

Use project to provide the target project’s slug:

speakeasy push --project my-project [command options]

When this option is not provided, the CLI falls back to using the following values, in this order:

The SPEAKEASY_AI_PROJECT environment variable
The defaultProjectSlug field of the current profile in ~/.config/speakeasy-ai/profile.json

`org`

Use org to provide the target organization’s slug:

speakeasy push --org my-org [command options]

When this option is not provided, the CLI falls back to using the following values, in this order:

The SPEAKEASY_AI_ORG environment variable
The organization of the current profile in ~/.config/speakeasy-ai/profile.json

`log-level`

Use log-level to set the base log level (the default is info). Because this is an app-level option, place it before the command name:

speakeasy --log-level debug [command] [command options]

The base log level can also be set via the SPEAKEASY_AI_LOG_LEVEL environment variable.

`log-pretty`

Use log-pretty to toggle pretty logging off. (By default, this option is set to true.) Because this is an app-level option, place it before the command name:

speakeasy --log-pretty=false [command] [command options]

Pretty logging can also be toggled via the SPEAKEASY_AI_LOG_PRETTY environment variable.

`profile`

Use profile to provide the profile name to use from ~/.config/speakeasy-ai/profile.json. Because this is an app-level option, place it before the command name:

speakeasy --profile production [command] [command options]

The profile name can also be set via the SPEAKEASY_AI_PROFILE environment variable.

`help`

Use help to view the help information for any command:

speakeasy [command] --help

Short form: -h

`version`

Use version to print the version of the speakeasy CLI.

speakeasy --version

Short form: -v