Reference

This section provides the reference for the available commands and flags for the Bluelink CLI.

Options that are marked with a boolean type are command line flags that do not take a value, however their config file and environment variable equivalents do take a value that should be set to one of true, false, 1 or 0.

Global Options

--config

The path to the configuration file to source CLI configuration from. Relative paths are expected to be relative to the current working directory.

Type: string

Default Value: When a value is not provided, the CLI will search for a file as per the configuration documentation.

--deploy-config-file

Environment Variable: BLUELINK_CLI_DEPLOY_CONFIG_FILE

Configuration Key: deployConfigFile

Type: string

Default Value: bluelink.deploy.jsonc

The path to the deploy configuration file that contains blueprint variable overrides and configuration for providers and transformers. This file is expected to be in the JSON with Commas and Comments format described in the Deploy Configuration doc.

If the file is not found, the CLI will send empty configuration to the Deploy Engine, which will in most cases result in an error in the response from the Deploy Engine.

This file is used by the stage-changes, deploy, destroy, plugins (install|uninstall) and validate commands.

When the Deploy Engine is running on the same machine as the CLI, the commands that use this file will automatically install any missing plugins defined in the dependencies section.

--connect-protocol

Environment Variable: BLUELINK_CLI_CONNECT_PROTOCOL

Configuration Key: connectProtocol

Type: string

Default Value: unix

Allowed Values: unix | tcp

The protocol to connect to the deploy engine with, this can be either unix or tcp. A unix socket can only be used on linux, macos and other unix-like operating systems. To use a unix socket on windows, you will need to use WSL 2 or above.

--engine-endpoint

Environment Variable: BLUELINK_CLI_ENGINE_ENDPOINT

Configuration Key: engineEndpoint

Type: string

Default Value: http://localhost:8325

The endpoint of the deploy engine api, this is used if --connect-protocol is set to tcp.

--engine-auth-config-file

Environment Variable: BLUELINK_CLI_ENGINE_AUTH_CONFIG_FILE

Configuration Key: engineAuthConfigFile

Type: string

Default Value: $HOME/.bluelink/config/engine.auth.json on Linux or macOS and %LOCALAPPDATA%\NewStack\Bluelink\config\engine.auth.json on Windows.

The path to the authentication configuration file for the deploy engine. This is used to authenticate with the deploy engine when using the stage-changes, deploy, destroy and validate commands.

See the Auth Configuration documentation for more information on what is expected to be present in this file.

init

bluelink init [options] [directory]

This command initialises a new blueprint project.

Run the command without any flags and go through the interactive prompts to create a new blueprint project:

bluelink init

Initialising a new blueprint project with a pre-selected template:

bluelink init --template aws-simple-api

Initialising a new blueprint project in a specific directory:

bluelink init --project-name my-project ./my-project

--template

Environment Variable: BLUELINK_CLI_INIT_TEMPLATE

Configuration Key: initTemplate

Default Value: scaffold

The template to use for the new blueprint project. The default template is a scaffold project that generates all the files needed for a project, populating the blueprint file with placeholder values.

--project-name

Environment Variable: BLUELINK_CLI_INIT_PROJECT_NAME

Configuration Key: initProjectName

Type: string

The name of the new blueprint project.

--blueprint-format

Environment Variable: BLUELINK_CLI_INIT_BLUEPRINT_FORMAT

Configuration Key: initBlueprintFormat

Type: string

Default Value: yaml

The format of the blueprint file to use. This can be either yaml or jsonc.

--no-git

Environment Variable: BLUELINK_CLI_INIT_NO_GIT

Configuration Key: initNoGit

Type: boolean

Default Value: false

If true, the project will not be initialised as a git repository.

[directory]

Type: string

The directory to initialise the new blueprint project in. If not provided, the project will be initialised in the current working directory.

templates

This is the command category for blueprint project templates. This is useful for listing available templates maintained by the Bluelink team.

list

This command lists all the available templates maintained by the Bluelink team.

Run the command without any flags to list all the available templates:

bluelink templates list

This is mostly useful in interactive mode where you can navigate and filter the templates available.

validate

This command validates a blueprint file. It will validate the project blueprint and other configuration files.

Run the command without any flags and go through the interactive prompts to validate a blueprint file:

bluelink validate

Validating a pre-selected local blueprint file:

bluelink validate --blueprint-file ./project.blueprint.yaml

Validating a pre-selected public URL:

bluelink validate --blueprint-file https://example.com/project.blueprint.yaml

Validating a pre-selected path to a file in an object storage bucket:

bluelink validate --blueprint-file s3://bucket-name/path/to/project.blueprint.yaml

--blueprint-file

Environment Variable: BLUELINK_CLI_VALIDATE_BLUEPRINT_FILE

Configuration Key: validateBlueprintFile

Default Value: project.blueprint.yaml

The blueprint file to validate. This can be a local file, a public URL or a path to a file in an object storage bucket. Local files can be specified as a relative or absolute path to the file. Public URLs must start with https:// and represent a valid URL to a blueprint file. Object storage bucket files must be specified in the format of {scheme}://{bucket-name}/{object-path}, where {scheme} is one of the following: s3, gcs, azureblob.

--check-blueprint-vars

Environment Variable: BLUELINK_CLI_VALIDATE_CHECK_BLUEPRINT_VARS

Configuration Key: validateCheckBlueprintVars

Type: boolean

Default Value: false

This flag enables validation of the blueprint variable values that are set in the deploy configuration file. By default, the CLI will not validate the blueprint variable overrides set in the deploy configuration file when validating a blueprint file.

--check-plugin-config

Environment Variable: BLUELINK_CLI_VALIDATE_CHECK_PLUGIN_CONFIG

Configuration Key: validateCheckPluginConfig

Type: boolean

Default Value: false

By default, the validate command only runs validation on a provided blueprint file. You can use the --check-blueprint-vars flag to validate the blueprint variable values set in the deploy configuration file. By default, configuration specific to providers and transformers is not validated as a part of this command. When this flag is set, the provider and transformer configuration sourced from deploy config files will be validated against the plugin configuration schemas.

stage

This command is used to stage changes for a blueprint instance. It should be used to generate change sets for updating existing blueprint instances or creating new blueprint instances. This will stream events from the change staging process as they occur.

The change set ID will be rendered in the output of the command once the change staging process has completed, this can the be used with the deploy command to deploy the change set.

Run the command without any flags and go through the interactive prompts to stage changes for a blueprint instance:

bluelink stage

Staging changes for a pre-selected local blueprint file for a new blueprint deployment:

bluelink stage --blueprint-file ./project.blueprint.yaml

Staging changes for a pre-selected local blueprint file for an existing blueprint instance:

bluelink stage --instance-name orders-stack --blueprint-file ./project.blueprint.yaml

--instance-name

Environment Variable: BLUELINK_CLI_STAGE_CHANGES_INSTANCE_NAME

Configuration Key: stageChangesInstanceName

Type: string

The unique name of an existing blueprint instance to stage changes for. The instance name should not be confused with the instance ID, which is a random identifier assigned to the instance by the deploy engine, the instance name is one you define when creating the instance. This should be left empty if the --instance-id flag is provided.

--instance-id

Environment Variable: BLUELINK_CLI_STAGE_CHANGES_INSTANCE_ID

Configuration Key: stageChangesInstanceId

Type: string

The random identifier assigned to an existing blueprint instance by the deploy engine. This should be left empty if the --instance-name flag is provided.

--blueprint-file

Environment Variable: BLUELINK_CLI_STAGE_CHANGES_BLUEPRINT_FILE

Configuration Key: stageChangesBlueprintFile

Default Value: project.blueprint.yaml

The blueprint file to use in the change staging process. This can be a local file, a public URL or a path to a file in an object storage bucket. Local files can be specified as a relative or absolute path to the file. Public URLs must start with https:// and represent a valid URL to a blueprint file. Object storage bucket files must be specified in the format of {scheme}://{bucket-name}/{object-path}, where {scheme} is one of the following: s3, gcs, azureblob.

--destroy

Environment Variable: BLUELINK_CLI_STAGE_CHANGES_DESTROY

Configuration Key: stageChangesDestroy

Type: boolean

Default Value: false

If true, the change set will be created for a destroy operation. This will only be used if the --instance-id or --instance-name flags are provided.

deploy

This command is used to deploy a change set for a given blueprint instance. It should be used to deploy updates to existing blueprint instances and new blueprint instances. This will stream events from the deployment process as they occur.

Run the command without any flags and go through the interactive prompts to deploy a change set for a blueprint instance:

bluelink deploy

Deploying a change set for a pre-selected instance using the latest change set in the deploy engine for that instance:

bluelink deploy --instance-name order-stack

Deploying a pre-selected instance and change set for a blueprint deployment:

bluelink deploy --instance-name order-stack --change-set-id a471bbb8-1267-4e65-873b-fa86bca71fcf

--change-set-id

Environment Variable: BLUELINK_CLI_DEPLOY_CHANGE_SET_ID

Configuration Key: deployChangeSetId

Type: string

The ID of the change set to deploy. This is the result of running the stage command for a new or existing blueprint instance. The change set ID is optional and the latest change set for a given instance name or ID will be used if not provided.

--instance-name

Environment Variable: BLUELINK_CLI_DEPLOY_INSTANCE_NAME

Configuration Key: deployInstanceName

Type: string

The user-defined unique name of the blueprint instance to deploy the change set for. This should be left empty if the --instance-id flag is provided.

--instance-id

Environment Variable: BLUELINK_CLI_DEPLOY_INSTANCE_ID

Configuration Key: deployInstanceId

Type: string

The generated ID of the blueprint instance to deploy the change set for. This should be left empty if the --instance-name flag is provided.

--rollback

Environment Variable: BLUELINK_CLI_DEPLOY_ROLLBACK

Configuration Key: deployRollback

Type: boolean

Default Value: false

If true, the deployment will be treated as a rollback operation for a previously deployed or destroyed blueprint instance. This can be used to indicate that the deployment is a "restoration" of a previously destroyed instance or a rollback to a previous state of a blueprint instance.

destroy

This command is used to destroy a blueprint instance. This will stream events from the destroy process as they occur.

Run the command without any flags and go through the interactive prompts to destroy a blueprint instance:

bluelink destroy

Destroying a pre-selected instance using the latest change set in the deploy engine for that instance:

bluelink destroy --instance-name order-stack

Destroying a pre-selected instance and change set for a blueprint deployment:

bluelink destroy --instance-name order-stack --change-set-id a471bbb8-1267-4e65-873b-fa86bca71fcf

--change-set-id

Environment Variable: BLUELINK_CLI_DESTROY_CHANGE_SET_ID

Configuration Key: destroyChangeSetId

Type: string

The ID of the change set to use to destroy the blueprint instance. This is the result of running the stage command with the --destroy flag for an existing blueprint instance. The change set ID is optional and the latest change set for a given instance name or ID will be used if not provided.

--instance-name

Environment Variable: BLUELINK_CLI_DESTROY_INSTANCE_NAME

Configuration Key: destroyInstanceName

Type: string

The user-defined unique name of the blueprint instance to destroy. This should be left empty if the --instance-id flag is provided.

--instance-id

Environment Variable: BLUELINK_CLI_DESTROY_INSTANCE_ID

Configuration Key: destroyInstanceId

Type: string

The generated ID of the blueprint instance to destroy. This should be left empty if the --instance-name flag is provided.

--rollback

Environment Variable: BLUELINK_CLI_DESTROY_ROLLBACK

Configuration Key: destroyRollback

Type: boolean

Default Value: false

If true, the destroy action will be treated as a rollback operation for a previously deployed blueprint instance. This can be used to indicate a rollback to a previous state where the current blueprint instance was deployed successfully but another part of the deployment failed, this typically happens when the current blueprint instance is a child of another blueprint instance that failed to deploy.

sync

This is the command category for syncing deployment state between different environments. These commands are useful for sharing deployment state between different environments when adopting a local deployment strategy. A local deployment strategy is where the deploy engine is running on the same machine as the CLI when running commands such as deploy or destroy.

An example use case would be a CI/CD pipeline that runs the stage and deploy commands for a blueprint deployment using a local deploy engine installation in the container or VM for the job. Through the use of these commands, the pipeline can import the deployment state from the previous run of the pipeline and deploy it to the same environment.

import

This command is used to import the entire state or specific blueprint instances from a local file or a remote source.

An example of importing the entire state from a local file:

bluelink sync import --file ./deployment-state.tar.gz

An example of importing one or more specific blueprint deployment instances from a remote source:

# The input file should be in the JSON format exported
# by the `export` command with the `--instances [idOrName1,idOrName2,...]` flag.
bluelink sync import --instances --file s3://bucket-name/path/to/instances-export.json

--instances

--file

export

This command is used to export the entire state or specific blueprint instances to be shared between environments.

An example of exporting the entire state to a local file:

bluelink sync export --file ./deployment-state.tar.gz

An example of exporting one or more specific blueprint deployment instances to a remote source:

bluelink sync export --instances stack-1,stack-2,stack-3 --file s3://bucket-name/path/to/instances-export.json

--instances

--file

plugins

This is the command category for managing deploy engine plugins installed on the machine that the CLI is running on.

login

This command logs into a plugin registry to allow the installation of plugins from specific protected registries by host.

An example of logging into a plugin registry:

bluelink login registry.customhost.com

The auth configuration for plugin registries is expected to be present in the $HOME/.bluelink/auth.json file. See the Plugin Registry Authentication Protocol for more information on how to authenticate with a plugin registry.

list

Lists all the plugins that are installed on the machine that the CLI is running on.

--type

Environment Variable: BLUELINK_CLI_PLUGINS_LIST_TYPE

Configuration Key: type

Allowed Values: provider | transformer | all

Default Value: all

The type of plugins to list.

install

bluelink plugins install [plugin-1] [plugin-2] ...

Installs one or more plugins on the machine that the CLI is running on. This command takes one or more plugin IDs as arguments.

An example of installing plugins defined in the deploy configuration file:

bluelink plugins install

An example of installing a single plugin:

bluelink plugins install newstack-cloud/aws

An example of installing multiple plugins:

bluelink plugins install newstack-cloud/aws newstack-cloud/azure registry.customhost.com/my-org/gcp

Plugins that exist in the bluelink registry do not need the full URL with the host name, only plugins stored in a custom registry need the full URL. For example, the plugin ID bluelink/aws will be resolved to registry.bluelink.dev/bluelink/aws.

As plugin IDs are globally unique, the CLI does not differentiate between provider and transformer plugins for the sake of installation.

uninstall

bluelink plugins uninstall [plugin-1] [plugin-2] ...

Uninstalls one or more plugins from the machine that the CLI is running on. This command takes one or more plugin IDs as arguments.

An example of uninstalling a single plugin:

bluelink plugins uninstall newstack-cloud/aws

An example of uninstalling multiple plugins:

bluelink plugins uninstall newstack-cloud/aws newstack-cloud/azure registry.customhost.com/my-org/gcp

Like with the install command, plugins that exist in the bluelink registry do not need the full URL with the host name, only plugins stored in a custom registry need the full URL. For example, the plugin ID bluelink/aws will be resolved to registry.bluelink.dev/bluelink/aws.

As plugin IDs are globally unique, the CLI does not differentiate between provider and transformer plugins when removing them.

help

For information on all the available commands and global options, run the following:

bluelink help

To get usage information for a specific command, run the following:

bluelink [command] --help

version

This command prints the version of the CLI along with the build OS, architecture and date of the build.

Run the command to print the version of the CLI:

bluelink version