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.
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.
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. These are the same Docker credentials requested by the opschain server configure command.
docker login --username opschaintrial
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.
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 Key | Optional | Description |
|---|---|---|
apiBaseUrl | no | OpsChain API server URL |
username | no | OpsChain API username |
password | yes | OpsChain API password - this or passwordCommand are required. |
passwordCommand | yes | Command 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). |
editor | no | editor used to edit properties |
requestTimeout | yes | modify the API request timeout (in milliseconds), increase this for slow servers/networks |
stepEmoji | yes | show emoji for the step status, default true - set to false to display status as text |
projectCode | yes | default OpsChain project code used for commands |
environmentCode | yes | default OpsChain environment code used for commands |
outputFormat | yes | default 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:
|
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
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
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.
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.