Skip to main content

OpsChain CLI

This document provides information on obtaining, configuring and using the OpsChain CLI.

When configuring the CLI, please note that some of the options described are optional and may not be required depending on your operating environment.

Installation

The OpsChain CLI binary can be downloaded from the opschain repository on GitHub.

tip

Ensure the native build matches the version of OpsChain that you are using. We suggest moving the binary to a location in your PATH to ensure it is easily accessible.

note

The native binaries offer support for the latest version of the respective OS (older versions of the respective OS may work).

Linux setup

Throughout the documentation we refer to the CLI as opschain. For Linux users we suggest renaming the binary to reflect the common name (and save some future typing):

mv opschain-* opschain

Linux users need to ensure that the CLI is executable:

chmod +x opschain

macOS setup

On macOS the OpsChain CLI needs to be extracted from the opschain-macos.dmg archive before use - i.e. drag and drop it to the desired destination, for example ~/bin.

Dev subcommand dependencies

The opschain dev subcommands depend on Docker. The docker executable must be available on the path and functional (i.e. docker run --rm hello-world should succeed) for these subcommands to be usable.

The open source Docker Engine package can be used on supported platforms. The open source upstream Moby package can be used as an alternative on supported platforms. Docker Desktop - or an alternative like Rancher Desktop, Colima, or Multipass (among others) - can be used on platforms without native Docker/Moby support.

Configure Docker Hub access

To use the OpsChain development environment you will need log in to Docker Hub as the opschaintrial user (or, if you have an enterprise licence for OpsChain, the opschainenterprise user). These are the same Docker credentials requested by the opschain server configure command.

docker login --username opschaintrial
tip

Use the DOCKER_CONFIG environment variable if you need to use multiple Docker Hub logins.

export DOCKER_CONFIG="$(pwd)/.docker" # this would need to be exported in all terminals where OpsChain is being used
docker login --username opschaintrial

Server subcommand dependencies

The OpsChain CLI opschain server subcommands depend on Helm and kubectl. These commands must be accessible on the PATH, and they must be configured to work with your target Kubernetes cluster.

OpsChain CLI configuration

The OpsChain CLI uses an .opschainrc configuration file. If .opschainrc is present in the current working directory it is used, otherwise, the .opschainrc from the user's home directory is used.

An example .opschainrc is provided in this repository.

The configuration file supports INI or JSON (with comments) formats.

CLI configuration locations

The OpsChain CLI configuration is loaded by the rc package. The rc documentation specifies the locations where the configuration file can be placed - the appname is opschain.

info

On Windows the USERPROFILE directory is used as the home directory.

Specifying the CLI configuration file

The opschain_config environment variable can be set to make the CLI use a specific configuration file. E.g.

opschain_config=./production.opschainrc opschain info

OpsChain CLI configuration settings

The .opschainrc file must be a valid JSON or INI file and supports the following configuration:

Configuration KeyOptionalDescription
apiBaseUrlnoOpsChain API server URL
usernamenoOpsChain API username
passwordyesOpsChain API password - this or passwordCommand are required.
passwordCommandyesCommand producing the API password (e.g. pass show opschain). If set, this will override the password configuration (even if it is pre-configured from an environment variable).
editornoeditor used to edit properties
requestTimeoutyesmodify the API request timeout (in milliseconds), increase this for slow servers/networks
stepEmojiyesshow emoji for the step status, default true - set to false to display status as text
projectCodeyesdefault OpsChain project code used for commands
environmentCodeyesdefault OpsChain environment code used for commands
outputFormatyesdefault OpsChain output format (if unset, the CLI will use the table format.

it can be set as a global default:
"outputFormat": "json"

or configured per operation:
"outputFormat": {
"create":"table",
"list":"json",
"show":"json"
}

The following operations are supported for multi-format outputs:
  • create
  • list
  • show

Environment variable configuration

OpsChain configuration can be overridden by using environment variables. This can be useful for temporarily overriding configuration.

Prefix the configuration key with opschain_ and set as an environment variable to override the value from the .opschainrc.

export opschain_projectCode=dev
opschain environment ls # this will list environments in the dev project without prompting

Timezones

The OpsChain CLI displays all timestamps in the timezone configured on the local machine. The exception to this are the timestamps included in the step phase log messages. These timestamps are generated by the OpsChain worker and step runner as the change is running and will be generated in the timezone these containers are configured in.

Using the OpsChain CLI with a proxy

info

This is only required if you are using an OpsChain server that needs to be accessed via a proxy. It is not mandatory.

The OpsChain CLI supports using a http(s) proxy by setting the relevant environment variables:

export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080
opschain change ls # or any other command

HTTP_PROXY is used when the OpsChain apiBaseUrl is an HTTP address. HTTPS_PROXY is used when the OpsChain apiBaseUrl is an HTTPS address.

Disabling TLS/SSL certificate verification

info

This is only required if you are using an OpsChain server that uses a non-trusted certificate. It is not mandatory.

The OpsChain CLI can be configured to ignore TLS/SSL certificate verification errors as follows:

export NODE_TLS_REJECT_UNAUTHORIZED=0
opschain change ls # or any other command

Shell completion

The OpsChain CLI supports shell completion. To use it run the opschain completion subcommand, for example:

opschain completion >> ~/.zshrc # this assumes you are using Zsh, modify as needed

Then reload your shell, e.g. by running exec zsh. Now the CLI will support tab-completion for commands and arguments.

OpsChain CLI container image

The OpsChain CLI is also distributed as a container image, limepoint/opschain-cli:${OPSCHAIN_VERSION}. The OPSCHAIN_VERSION used should match the server installation version - if unknown this can be seen via the api/info API endpoint.

Some examples of how the CLI image can be used are shown below:

OPSCHAIN_VERSION="$(curl --user opschain:password 'http://localhost:3000/api/info' | jq -r .data.attributes.version)" # modify the API address and credentials as required, or enter the value manually if known
docker run -ti -v ~/.opschainrc:/.opschainrc limepoint/opschain-cli:${OPSCHAIN_VERSION} environment ls
# with files:
docker run -ti -v $(pwd):$(pwd) -v ~/.opschainrc:$(pwd)/.opschainrc -w $(pwd) limepoint/opschain-cli:${OPSCHAIN_VERSION} environment set-properties -f ./properties.json

Using the OpsChain CLI in an OpsChain change

The OpsChain CLI container image also makes it simple to access the OpsChain CLI within a custom step runner Dockerfile:

ARG OPSCHAIN_VERSION
ARG OPSCHAIN_BASE_RUNNER
FROM limepoint/opschain-cli:${OPSCHAIN_VERSION} as cli
FROM ${OPSCHAIN_BASE_RUNNER}

...

COPY --from=cli /opschain /usr/bin/opschain

The CLI configuration can be included in the environment variable properties using the environment variable configuration

Server management

The OpsChain CLI includes commands for configuring and managing OpsChain server instances. Learn more about the specific subcommands by running opschain server --help.

These commands create and manage the .env and values.yaml configuration files for an installation. For this reason we suggest creating a specific directory to store this configuration, and maintaining it as a Git repository if desired. All opschain server commands must then be run from this directory.

Supported platforms

The opschain server subcommands can be run on Linux, macOS and Windows.

On Windows, we suggest using a modern terminal like the Windows Terminal from the Microsoft Store. The Powershell terminal and Command Prompt are also supported in a best-effort manner.

tip

We suggest avoiding Git Bash with the OpsChain CLI as it renders the prompts incorrectly.

Configuration overrides

The opschain server deploy/start/stop CLI commands will look for a values.override.yaml file in the current directory and will use it to override configuration in values.yaml.

This allows customisations to the values.yaml file to be stored and re-applied automatically, rather than needing to modify the values.yaml file after running the opschain server configure command.

The override file is provided to Helm and will override values in the main values.yaml using Helm's values file merging.

Full reconfiguration

When upgrading or reconfiguring an existing installation, the server configuration command will not re-ask questions whose answers cannot change.

If you would like to re-run the full server configuration remove/move the .env file (e.g. mv .env .env.old) and re-run opschain server configure.