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>
Arguments | Required? | Description |
---|---|---|
Name | No | The name of the instance to list. Use the full name of the instance surrounded by double or single quotes. |
Flags | Required? | Description |
---|---|---|
-d, --deployments | No | Shows only deployment instances. |
-m, --mocks | No | Shows only mock instances. |
-c, --codes | No | Shows only code instances. |
Examples | Description |
---|---|
blackbird instance list | Shows details for all instances. |
blackbird instance list “Simple API Mock” | Shows details for the instance named "Simple API Mock". |
blackbird instance list -m | Shows 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>
Arguments | Required? | Description |
---|---|---|
Name | Yes | The 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>
Arguments | Required? | Description |
---|---|---|
Header Name | Yes | The name of the API key header. |
Value | Yes | The value of the API key. This value can be any string. |
Example | Description |
---|---|
blackbird apikey create simple-key thisismyvalue | Creates 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>
Arguments | Required? | Description |
---|---|---|
Header Name | Yes | The name of the API key header you want to delete. |
Example | Description |
---|---|
blackbird apikey delete simple-key | Deletes 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>
Arguments | Required? | Description |
---|---|---|
Header Key | Yes | The name of the existing API key header. |
Instance Name | Yes | The 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. |
Example | Description |
---|---|
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>
Arguments | Required? | Description |
---|---|---|
Header Key | Yes | The name of the existing API key header. |
Instance Name | Yes | The 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. |
Example | Description |
---|---|
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.
Flags | Required? | Examples |
---|---|---|
-a, --active | No | Lists API key headers that have been enabled for one or more instances. |
-i, --inactive | No | Lists 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
Arguments | Required | Description |
---|---|---|
Name | Yes | The name of the API you're creating. |
Flags | Required? | Description |
---|---|---|
-s, –-spec-path=STRING | Yes | The path to an OpenAPI file. |
Examples | Description |
---|---|
blackbird api create "Simple API" --spec-path=./simple-api.yaml | Creates 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>
Arguments | Required? | Description |
---|---|---|
Slug Name | No | The slug name of the API for which you want to see details. |
Examples | Description |
---|---|
blackbird api list | Returns details for all APIs. |
blackbird api list simple-api | Returns 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
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the API you want to update. |
Flags | Required? | Description |
---|---|---|
-s, –-spec-path=STRING | Yes | The path to an OpenAPI file. |
Examples | Description |
---|---|
blackbird api update "Simple API" --spec-path=./simple-api-updated.yaml | Updates 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>
Arguments | Required? | Description |
---|---|---|
Slug Name | Yes | The slug name of the API you want to delete. |
Examples | Description |
---|---|
blackbird api delete simple-api | Deletes 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>
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the new mock instance. |
Flags | Required? | Description |
---|---|---|
-n, --api-name=STRING | Yes, unless using a spec path. | The slug name of the existing API you want to use to create the mock instance. |
--apikey-header=STRING | No | Enables 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=STRING | No | The 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. |
Examples | Description |
---|---|
blackbird mock create simple-api-mock -n simple-api | Creates 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.yaml | Creates 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>
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the mock instance you want to update. |
Flags | Required? | Description |
---|---|---|
-n, --api-name=STRING | Yes, 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=STRING | No | Enables 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=STRING | No | The path to an OpenAPI file to update the mock instance with. |
Examples | Description |
---|---|
blackbird mock update simple-api-mock -n another-api | Updates 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>
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the mock instance you want to delete. |
Examples | Description |
---|---|
blackbird mock delete simple-api-mock | Deletes 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
Arguments | Required? | Description |
---|---|---|
Name | Yes, and must come before ‘get’ | The name of the mock instance. |
Examples | Description |
---|---|
blackbird mock config simple-api-mock get | Returns 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>
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the mock instance. |
Configuration Parameter(s) | Yes | The configuration parameters you want to set. |
Examples | Description |
---|---|
blackbird mock config simple-api-mock set dynamic=false | Disables 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.
Flags | Required? | 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-template | If 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=STRING | Yes | The path to an OpenAPI spec file to use with the code generator. |
-l, --local-template=STRING | If 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=STRING | Yes | The destination directory where you want to store the generated project. Folders will be created if they don't exist. |
Examples | Description |
---|---|
blackbird code generate -s simple-api.yaml -t go -o ~/Documents/blackbird/simple-api-test | Generates 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-test | Generates 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
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the application you want to run. This must be all lowercase. |
Flags | Required? | Description |
---|---|---|
-d, --dockerfile=STRING | No | The name of your Dockerfile in the current directory. |
-c, --context=STRING | Yes | The path to the source code directory you want to include in the image. |
-e, --envfile=ENVFILE | No | The path to a .env file that contains lines of KEY=VALUE. |
--expose=EXPOSE | No | The port to expose from the container network. The format should be ADDRESS:LOCAL-PORT:PORT or LOCAL-PORT:PORT. |
-p, --port="80" | No | The service port or port name. |
-l, --local-port=8080 | No | The local port to forward to. |
--apikey-header=STRING | No | The name of one of your API key headers to enable for this code instance. |
Examples | Description |
---|---|
blackbird code run simple-api -d Dockerfile -c . -l 80 | Builds 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
Arguments | Required? | Description |
---|---|---|
Name | No | The name of the application you want to run. This must be all lowercase. |
Flags | Required? | Description |
---|---|---|
-d, --dockerfile=STRING | No | The name of the Dockerfile in your current directory. |
-c, --context=STRING | Yes | The path to the source code directory you want to include in the image. |
-e, --envfile=ENVFILE | No | The path to a .env file that contains lines of KEY=VALUE. |
--expose=EXPOSE | No | The port to expose from the container network. The format should be ADDRESS:LOCAL-PORT:PORT or LOCAL-PORT:PORT. |
-p, --port="80" | No | The service port or port name. |
-l, --local-port=8080 | No | The local port to forward to. |
--apikey-header=STRING | No | The name of one of your API key headers to enable for this code instance. |
--target="debug:2345" | No | Builds the target stage and port to attach to the debugger. The default can be overridden using ':'. |
Examples | Description |
---|---|
blackbird code debug simple-api -d Dockerfile -c . -l 80 | Builds 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
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the deployment you want to create. |
Flags | Required? | Description |
---|---|---|
-d, --dockerfile=DOCKERFILE | Yes | The path to a Dockerfile. |
-c, --context=STRING | Yes | The path to the source code directory you want to include in the image. |
-e, --envfile=ENVFILE | No | The path to a .env file that contains lines of KEY=VALUE. |
--apikey-header=STRING | No | The name of the API key header you want to enable for this deployment. |
Examples | Description |
---|---|
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>
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the deployment for which you want to show details. |
Flags | Required? | Description |
---|---|---|
-l, --logs | No | Shows 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
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the deployment you want to update. |
Flags | Required? | Description |
---|---|---|
-d, --dockerfile=DOCKERFILE | Yes | The path to a Dockerfile. |
-c, --context=STRING | Yes | The path to the source code directory you want to include in the image. |
-e, --envfile=ENVFILE | No | The path to a .env file that contains lines of KEY=VALUE. |
--apikey-header=STRING | No | The name of the API key header you want to enable for this deployment. |
Examples | Description |
---|---|
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>
Arguments | Required? | Description |
---|---|---|
Name | Yes | The name of the deployment you want to delete. |