The Heroku AI CLI plugin lets you provision, inspect, and use AI model resources without leaving your terminal. Use the commands below to manage model lifecycles, run inference, and connect Model Context Protocol (MCP) servers and tools.
Installation
The AI plugin ships with the Heroku CLI (v10.8.0 and later). Update the CLI if you do not see the heroku ai:*
commands.
Install or update the Heroku CLI
Visit heroku.com/cli and follow the platform-specific instructions. Then confirm the version: Update plugins
Pull the latest plugins (including heroku-ai) to ensure you have current commands: Quick workflow
Provision a model
heroku ai:models:create claude-4-sonnet --app my-app
my-app.Send a prompt
heroku ai:models:call claude-4-sonnet --app my-app --prompt "Hello!"
--json to write raw JSON.Review available models
Lists all provisionable models, including their default aliases. Command reference
Model lifecycle
heroku ai:models:list
Purpose: List every model that can be provisioned in your region. heroku ai:models is an alias.
heroku ai:models:list [--json]
| Flag | Description |
|---|
--json | Return machine-readable output for automation and scripting. |
heroku ai:models:list --json | jq '.[0].name'
heroku ai:models:create
Purpose: Provision a model resource and attach it to an app.
heroku ai:models:create <model-name> --app <app-name> [--as <alias>] [--confirm <app-name>] [--remote <remote>]
<model-name>: ID of the model you want to provision (for example claude-4-5-sonnet).
Options
| Flag | Description |
|---|
--app <app-name> | Required. App that owns the new model resource. |
--as <alias> | Optional alias for the resource (for example chat-default). |
--confirm <app-name> | Skip the confirmation prompt; value must match the app name. |
--remote <remote> | Target the app referenced by a Git remote. |
heroku ai:models:create claude-4-5-sonnet --app sample-app --as chat-default
heroku ai:models:destroy
Purpose: Permanently delete a model resource.
heroku ai:models:destroy <resource-alias> --app <app-name> [--confirm <app-name>] [--force] [--remote <remote>]
<resource-alias>: Alias or resource ID to remove (for example chat-default or claude-4-5-sonnet-basic-43973).
Options
| Flag | Description |
|---|
--app <app-name> | Required. App currently attached to the resource. |
--confirm <app-name> | Skip the confirmation prompt; value must match the app name. |
--force | Remove the resource even if it is shared with other apps. |
--remote <remote> | Target the app referenced by a Git remote. |
heroku ai:models:destroy chat-default --app sample-app --confirm sample-app
heroku ai:models:info
Purpose: Inspect the status and configuration of one or all model resources on an app.
heroku ai:models:info [<resource-alias>] --app <app-name> [--json] [--remote <remote>]
<resource-alias>: Optional. Provide an alias to limit output to a single resource.
Options
| Flag | Description |
|---|
--app <app-name> | Required. App to query. |
--json | Emit machine-readable output. |
--remote <remote> | Target the app referenced by a Git remote. |
heroku ai:models:info --app sample-app
heroku ai:models:info chat-default --app sample-app --json
Share model access between apps
heroku ai:models:attach
Purpose: Attach an existing model resource to another app.
heroku ai:models:attach <resource-id> --source-app <source-app> --target-app <target-app> [--as <alias>] [--confirm <target-app>] [--remote <remote>]
<resource-id>: Resource ID or alias from the source app (for example claude-4-5-sonnet-basic-43973).
Options
| Flag | Description |
|---|
--source-app <source-app> | Required. App that already owns the resource. |
--target-app <target-app> | Required. App that should receive the resource. |
--as <alias> | Optional alias to assign on the target app. |
--confirm <target-app> | Skip the overwrite prompt on the target app. |
--remote <remote> | Target the app referenced by a Git remote. |
heroku ai:models:attach claude-4-5-sonnet-basic-43973 \
--source-app shared-services \
--target-app reporting-app \
--as chat-reporting
heroku ai:models:detach
Purpose: Remove a model alias from an app without deleting the underlying resource.
heroku ai:models:detach <resource-alias> --app <app-name> [--remote <remote>]
<resource-alias>: Alias to remove from the app (for example chat-reporting).
Options
| Flag | Description |
|---|
--app <app-name> | Required. App that currently uses the alias. |
--remote <remote> | Target the app referenced by a Git remote. |
heroku ai:models:detach chat-reporting --app reporting-app
Run inference
heroku ai:models:call
Purpose: Send a prompt to a model resource and stream the response locally.
heroku ai:models:call <resource-alias> --app <app-name> \
[--prompt "<prompt>"] [--opts '<json>'] [--optfile <file>] \
[--output <path>] [--json] [--remote <remote>]
<resource-alias>: Alias or resource ID to invoke (for example chat-default).
Options
| Flag | Description |
|---|
--app <app-name> | Required. App that owns the resource. |
--prompt "<prompt>" | Provide a text prompt directly on the command line. |
--opts '<json>' | Pass additional options as a JSON string (for example {"max_tokens":512}). |
--optfile <file> | Pass options from a JSON file. |
--output <path> | Write the response body to a file. |
--json | Emit the raw API response as JSON. |
--remote <remote> | Target the app referenced by a Git remote. |
heroku ai:models:call chat-default --app sample-app \
--prompt "Summarize the latest release notes." \
--output release-summary.md
heroku ai:models:call image-default --app sample-app \
--prompt "Generate a hero image of a cloud data center at dusk." \
--opts '{"quality":"hd"}' --json
Monitoring and usage
heroku ai:models:info
Purpose: Display stats and the current state of your model resources.
heroku ai:models:info <resource-alias> --app <app-name> [--json]
<resource-alias>: Resource ID or alias to inspect (for example claude-4-sonnet or chat-default).
Options
| Flag | Description |
|---|
--app <app-name> | Required. App that owns the resource. |
--json | Emit machine-readable output. |
heroku ai:models:info chat-default --app my-app
heroku usage:addons
Purpose: View usage data for AI model resources, including token counts for the current billing period.
heroku usage:addons --app <app-name> --team <team-name>
| Flag | Description |
|---|
--app <app-name> | Required. App to query usage for. |
--team <team-name> | Required. Team that owns the app. |
heroku usage:addons -a example-app -t example-team
=== Usage for example-team
Add-on Meter Quantity
───────────────────────── ────── ────────
inference-amorphous-42410 input 8
inference-amorphous-42410 output 12
- input: Number of tokens processed (sent to the model) in the current billing period
- output: Number of tokens generated (received from the model) in the current billing period
For pricing details based on token usage, see Pricing.
heroku ai:mcp
Purpose: Retrieve the MCP server URL for a Heroku Inference add-on.
heroku ai:mcp [<addon-name>] --app <app-name> [--json] [--remote <remote>]
<addon-name>: Optional. Defaults to heroku-inference.
Options
| Flag | Description |
|---|
--app <app-name> | Required. App that owns the add-on. |
--json | Return the response as JSON. |
--remote <remote> | Target the app referenced by a Git remote. |
heroku ai:mcp --app sample-app --json
heroku ai:tools:list [<addon-name>] --app <app-name> [--json] [--remote <remote>]
<addon-name>: Optional. Defaults to heroku-inference.
Options
| Flag | Description |
|---|
--app <app-name> | Required. App that owns the add-on. |
--json | Return the response as JSON. |
--remote <remote> | Target the app referenced by a Git remote. |
heroku ai:tools:list --app sample-app --json | jq '.tools[].name'
Documentation and help
heroku ai:docs
Purpose: Open the Heroku Managed Inference and Agents documentation in your browser.
heroku ai:docs [--browser <browser>]
| Flag | Description |
|---|
--browser <browser> | Specify a browser such as firefox, safari, or edge. Defaults to the system browser. |
heroku ai:docs --browser firefox
