Docsright arrowBlackbirdright arrowAmbassador Blackbird CLI Commands Reference

18 min • read

Ambassador Blackbird CLI Commands Reference

Use this reference to learn about the available CLI commands for Blackbird, including their use cases, flags, arguments, and examples.

Consider the following when using this reference:

  • Running blackbird help outputs the entire list of commands.
  • All commands also have the flags --help or -h, which display available flags, arguments, and subcommands.
  • All examples use an API named Simple API, which has a slug name of simple-api.
  • You can use the blackbird api list command to view the slug name of the API. The slug name is the name of the API in a format that's easier to read.

General

Command: blackbird login

Function: Opens a new browser window for logging in to Blackbird. This command must be run prior to attempting any other commands.

Command: blackbird version

Function: Shows the current version of Blackbird. View our release notes for version details. To upgrade, download the latest binary of the CLI using the command in the Download CLI section.

Command: blackbird logout

Function: Logs the current user out of Blackbird.

Command: blackbird subscription info

Function: Shows detailed subscription information, including the status, current plan, start and end dates, limits, and usage.

Command: blackbird instance list

Function: Lists the name, type, status, API key headers, URL, and user for deployment, mock, and code instances.

Usage: blackbird instance list <name>

ArgumentsRequired?Description
NameNoThe name of the instance to list. Use the full name of the instance surrounded by double or single quotes.
FlagsRequired?Description
-d, --deploymentsNoShows only deployment instances.
-m, --mocksNoShows only mock instances.
-c, --codesNoShows only code instances.
ExamplesDescription
blackbird instance listShows details for all instances.
blackbird instance list “Simple API Mock”Shows details for the instance named "Simple API Mock".
blackbird instance list -mShows details for all mock instances.

Command: blackbird organization list

Function: Lists all Blackbird organizations you belong to.

Usage: blackbird organization list or blackbird org list

Command: blackbird organization set

Function: Sets a specific organization as your active organization. All commands run will target your active organization.

Usage: blackbird organization set <name> or blackbird org set <name>

ArgumentsRequired?Description
NameYesThe name of the organization. Use the name surrounded by double quotes.

API Keys

Command: blackbird apikey create

Function: Creates an API key header to secure an instance. Save the name of your API key so you can access it in the future.

Usage: blackbird apikey create <header-name> <value>

ArgumentsRequired?Description
Header NameYesThe name of the API key header.
ValueYesThe value of the API key. This value can be any string.
ExampleDescription
blackbird apikey create simple-key thisismyvalueCreates an API key with the name "simple-key" and value "thisismyvalue".

Command: blackbird apikey delete

Function: Deletes an existing API key header.

Usage: blackbird apikey delete <header-name>

ArgumentsRequired?Description
Header NameYesThe name of the API key header you want to delete.
ExampleDescription
blackbird apikey delete simple-keyDeletes the API key named "simple-key".

Command: blackbird apikey enable

Function: Enables an API key header for a mock or deployment. Requests can't access the mock or deployment instance without the API key header in the request.

Usage: blackbird apikey enable <header-key> <instance-name>

ArgumentsRequired?Description
Header KeyYesThe name of the existing API key header.
Instance NameYesThe name of the mock or deployment instance for which you want to enable the API key header. Use the full name of the instance surrounded by double or single quotes.
ExampleDescription
blackbird apikey enable simple-key “Simple API Mock”Enables the API key "simple-key" for the instance "Simple API Mock".

Command: blackbird apikey disable

Function: Disables an API key header for a mock or deployment. When the API key is disabled for a mock or deployment, any request can access the mock or deployment instance.

Usage: blackbird apikey disable <header-key> <instance-name>

ArgumentsRequired?Description
Header KeyYesThe name of the existing API key header.
Instance NameYesThe name of the mock or deployment instance for which you want to disable the API key header. Use the full name of the instance surrounded by double or single quotes.
ExampleDescription
blackbird apikey disable simple-key “Simple API Mock”Disables the API key "simple-key" for the instance "Simple API Mock".

Command: blackbird apikey list

Function: Lists all API key headers, mock or deployment instances for which each header is enabled, and when each header was created.

FlagsRequired?Examples
-a, --activeNoLists API key headers that have been enabled for one or more instances.
-i, --inactiveNoLists API key headers that haven't been enabled for one or more instances.

API

Command: blackbird api create

Function: Creates an API within Blackbird. To use, enter blackbird api create followed by the API name and the OpenAPI spec path.

Usage: blackbird api create <name> –-spec-path=STRING

ArgumentsRequiredDescription
NameYesThe name of the API you're creating.
FlagsRequired?Description
-s, –-spec-path=STRINGYesThe path to an OpenAPI file.
ExamplesDescription
blackbird api create "Simple API" --spec-path=./simple-api.yamlCreates an API named Simple API using the OpenAPI file located at ./simple-api.yaml.

Command: blackbird api list

Function: Lists the name, slug name, spec file, and user who created the API for each API matching the given API slug name. If no name is given, all APIs will be returned.

Usage: blackbird api list <slug-name>

ArgumentsRequired?Description
Slug NameNoThe slug name of the API for which you want to see details.
ExamplesDescription
blackbird api listReturns details for all APIs.
blackbird api list simple-apiReturns details for an API named "simple-api".

Command: blackbird api update

Function: Updates an existing API in Blackbird.

Usage: blackbird api update <name> --spec-path=STRING

ArgumentsRequired?Description
NameYesThe name of the API you want to update.
FlagsRequired?Description
-s, –-spec-path=STRINGYesThe path to an OpenAPI file.
ExamplesDescription
blackbird api update "Simple API" --spec-path=./simple-api-updated.yamlUpdates an existing API named "Simple API" using the OpenAPI file located at ./simple-api-updated.yaml.

Command: blackbird api delete

Function: Deletes an API. To use, enter blackbird api delete followed by the API name. If the API is associated with any mocks or deployments, a prompt will appear asking if you want to remove all associated instances.

Usage: blackbird api delete <slug-name>

ArgumentsRequired?Description
Slug NameYesThe slug name of the API you want to delete.
ExamplesDescription
blackbird api delete simple-apiDeletes the API named "simple-api".

Mock

Command: blackbird mock create

Function: Creates a new mock using an existing API or a filepath to an OpenAPI spec.

Usage: blackbird mock create <name>

ArgumentsRequired?Description
NameYesThe name of the new mock instance.
FlagsRequired?Description
-n, --api-name=STRINGYes, unless using a spec path.The slug name of the existing API you want to use to create the mock instance.
--apikey-header=STRINGNoEnables an existing API key header for the mock. After enabling an API key header for a mock, all future requests to the mock must contain the API key header.
-s, --spec-path=STRINGNoThe path to the OpenAPI file you want to use to create the mock instance. Use this flag if you're creating a mock instance for an API that you didn't create using Blackbird.
ExamplesDescription
blackbird mock create simple-api-mock -n simple-apiCreates a mock named "simple-api-mock" from an existing API with the slug name "simple-api".
blackbird mock create simple-api-mock -s ./simple-api.yamlCreates a mock named "simple-api-mock" from an OpenAPI specification file.

Command: blackbird mock list

Function: Lists the name, type, status, API key headers, URL, and user who created the mock for every mock in your organization.

Command: blackbird mock update

Function: Updates an existing mock instance for an API.

Usage: blackbird mock update <name>

ArgumentsRequired?Description
NameYesThe name of the mock instance you want to update.
FlagsRequired?Description
-n, --api-name=STRINGYes, unless using a spec path (not recommended)The slug name of the existing API you want to use to update the mock instance.
--apikey-header=STRINGNoEnables an existing API key header for the mock. After enabling an API key header for a mock, all future requests to the mock must contain the API key header.
-s, --spec-path=STRINGNoThe path to an OpenAPI file to update the mock instance with.
ExamplesDescription
blackbird mock update simple-api-mock -n another-apiUpdates an existing mock named "simple-api-mock" using the existing API with the slug name "another-api".

Command: blackbird mock delete

Function: Deletes a mock instance for an API. If the mock instance is associated with an API, a prompt will appear asking if you want to remove all associated APIs.

Usage: blackbird mock delete <name>

ArgumentsRequired?Description
NameYesThe name of the mock instance you want to delete.
ExamplesDescription
blackbird mock delete simple-api-mockDeletes the mock named "simple-api-mock".

Command: blackbird mock config <name> get

Function: Obtains the configuration of a mock instance.

Usage: blackbird mock config <name> get

ArgumentsRequired?Description
NameYes, and must come before ‘get’The name of the mock instance.
ExamplesDescription
blackbird mock config simple-api-mock getReturns the configuration for the mock instance named "simple-api-mock".

Command: blackbird mock config <mock-name> set

Function: Sets the configuration of a mock instance.

Usage: blackbird mock config <name> set <config-parameter>

ArgumentsRequired?Description
NameYesThe name of the mock instance.
Configuration Parameter(s)YesThe configuration parameters you want to set.
ExamplesDescription
blackbird mock config simple-api-mock set dynamic=falseDisables dynamic data generation for the mock instance named "simple-api-mock".

Code

Command: blackbird code generate

Function: Locally generates code in Go for an API. You can utilize an existing template from Blackbird, use your own, or use none. Using a template allows you to customize the generated code by adding variables, configuring renames, and choosing which modules to enable. An existing API in our API catalog is required to generate code.

FlagsRequired?Description
-t, --template=<template name>If you're using an existing template, yes. One of the three template flags (-t, --no-template, or -l) is required to generate code.The name of an existing template you want to use as a base. Currently, the only available template is Go. Templates can be found in our GitHub Generators Repository.
--no-templateIf you're not using a template, yes. One of the three template flags (-t, --no-template, or -l) is required to generate code.If set, no template will be used.
-s, --spec-path=STRINGYesThe path to an OpenAPI spec file to use with the code generator.
-l, --local-template=STRINGIf you're using a local template, yes. One of the three template flags (-t, --no-template, or -l) is required to generate code.Path to a local template to use when generating a new project.
-o, --output=STRINGYesThe destination directory where you want to store the generated project. Folders will be created if they don't exist.
ExamplesDescription
blackbird code generate -s simple-api.yaml -t go -o ~/Documents/blackbird/simple-api-testGenerates a code project located at ~/Documents/blackbird/simple-api-test using an OpenAPI specification file located at simple-api.yaml with the existing Go template.
blackbird code generate -s simple-api.yaml --no-template -o ~/Documents/blackbird/simple-api-testGenerates a code project located at ~/Documents/blackbird/simple-api-test.

Command: blackbird code run

Function: Containerizes code and runs it locally. This spins up a container with your code, and you can utilize the same endpoint from our mock server to reach your code.

Usage: blackbird code run <name> --context=STRING

ArgumentsRequired?Description
NameYesThe name of the application you want to run. This must be all lowercase.
FlagsRequired?Description
-d, --dockerfile=STRINGNoThe name of your Dockerfile in the current directory.
-c, --context=STRINGYesThe path to the source code directory you want to include in the image.
-e, --envfile=ENVFILENoThe path to a .env file that contains lines of KEY=VALUE.
--expose=EXPOSENoThe port to expose from the container network. The format should be ADDRESS:LOCAL-PORT:PORT or LOCAL-PORT:PORT.
-p, --port="80"NoThe service port or port name.
-l, --local-port=8080NoThe local port to forward to.
--apikey-header=STRINGNoThe name of one of your API key headers to enable for this code instance.
ExamplesDescription
blackbird code run simple-api -d Dockerfile -c . -l 80Builds and runs a local container with a remote server named "simple-api" from the Dockerfile located in the current directory, accessible via port 80.

Command: blackbird code debug

Function: Uses the same functionality as blackbird code run, but also starts a debugger and waits for a debugger frontend to attach.

Usage: blackbird code debug <name> --context=STRING

ArgumentsRequired?Description
NameNoThe name of the application you want to run. This must be all lowercase.
FlagsRequired?Description
-d, --dockerfile=STRINGNoThe name of the Dockerfile in your current directory.
-c, --context=STRINGYesThe path to the source code directory you want to include in the image.
-e, --envfile=ENVFILENoThe path to a .env file that contains lines of KEY=VALUE.
--expose=EXPOSENoThe port to expose from the container network. The format should be ADDRESS:LOCAL-PORT:PORT or LOCAL-PORT:PORT.
-p, --port="80"NoThe service port or port name.
-l, --local-port=8080NoThe local port to forward to.
--apikey-header=STRINGNoThe name of one of your API key headers to enable for this code instance.
--target="debug:2345"NoBuilds the target stage and port to attach to the debugger. The default can be overridden using ':'.
ExamplesDescription
blackbird code debug simple-api -d Dockerfile -c . -l 80Builds and runs a local container with a remote server and attached debugger front-end named "simple-api" from the Dockerfile located in the current directory, accessible via port 80.

Command: blackbird code list

Function: Lists the name, type, status, API key headers, URL, and user who created the instance for any active instances of code run using the blackbird code run or blackbird code debug command in your organization.

Deployment

Command: blackbird deployment create

Function: Containerizes and deploys code to your Blackbird-hosted environment.

Usage: blackbird deployment create <name> --dockerfile=DOCKERFILE --context=STRING

ArgumentsRequired?Description
NameYesThe name of the deployment you want to create.
FlagsRequired?Description
-d, --dockerfile=DOCKERFILEYesThe path to a Dockerfile.
-c, --context=STRINGYesThe path to the source code directory you want to include in the image.
-e, --envfile=ENVFILENoThe path to a .env file that contains lines of KEY=VALUE.
--apikey-header=STRINGNoThe name of the API key header you want to enable for this deployment.
ExamplesDescription
blackbird deployment create simple-api -d Dockerfile -c .Containerizes and deploys an application named "simple-api" using a Dockerfile and source code in the current directory.

Command: blackbird deployment list

Function: Lists all deployments.

Command: blackbird deployment status

Function: Shows detailed information about a deployment.

Usage: blackbird deployment status <name>

ArgumentsRequired?Description
NameYesThe name of the deployment for which you want to show details.
FlagsRequired?Description
-l, --logsNoShows application logs for the deployment.

Command: blackbird deployment update

Function: Updates an existing deployment in the hosted environment.

Usage: blackbird deployment update <name> --dockerfile=DOCKERFILE --context=STRING

ArgumentsRequired?Description
NameYesThe name of the deployment you want to update.
FlagsRequired?Description
-d, --dockerfile=DOCKERFILEYesThe path to a Dockerfile.
-c, --context=STRINGYesThe path to the source code directory you want to include in the image.
-e, --envfile=ENVFILENoThe path to a .env file that contains lines of KEY=VALUE.
--apikey-header=STRINGNoThe name of the API key header you want to enable for this deployment.
ExamplesDescription
blackbird deployment update simple-api -d Dockerfile -c .Updates a deployment named "simple-api" using a Dockerfile named "Dockerfile" and source code in the current directory. This builds a new image and replaces the existing image in the hosted environment.

Command: blackbird deployment delete

Function: Removes a deployment.

Usage: blackbird deployment delete <name>

ArgumentsRequired?Description
NameYesThe name of the deployment you want to delete.