CloudTruth CLI

The CloudTruth CLI tool is used for interacting with the CloudTruth configuration management service. In order to use the CLI you must have an active CloudTruth account.

Installation

The CLI is available as package with a binary executable. Download the version built for your Platform: https://github.com/cloudtruth/cloudtruth-cli/releases/

Here is an installation guide for your preferred distribution that will install the latest version of the CLI.

Debian/Ubuntu
MacOS
Windows
RedHat/CentOS
Debian/Ubuntu
CT_CLI_VERSION=$(curl --silent "https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest" | grep "tag_name" | sed -E 's/.*"([^"]+)".*/\1/')
curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/${CT_CLI_VERSION}/cloudtruth_${CT_CLI_VERSION}_amd64.deb
sudo dpkg -i cloudtruth_${CT_CLI_VERSION}_amd64.deb
MacOS
export CT_CLI_VERSION=$(curl --silent "https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest" | grep "tag_name" | sed -E 's/.*"([^"]+)".*/\1/')
curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/$CT_CLI_VERSION/cloudtruth-$CT_CLI_VERSION-x86_64-apple-darwin.tar.gz
tar xzf cloudtruth-$CT_CLI_VERSION-x86_64-apple-darwin.tar.gz
sudo install -m 755 -o root "cloudtruth-$CT_CLI_VERSION-x86_64-apple-darwin/cloudtruth" /usr/local/bin
Windows

These commands will download the Windows executable and extract the contents into your Windows Temp directory then copy the executable to C:\cloudtruth. Run them sequentially.

$CT_CLI_VERSION = ((Invoke-WebRequest https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest).Content | ConvertFrom-Json).tag_name
Invoke-WebRequest -outfile $ENV:TEMP\cloudtruth.zip https://github.com/cloudtruth/cloudtruth-cli/releases/download/$CT_CLI_VERSION/cloudtruth-$CT_CLI_VERSION-x86_64-pc-windows-msvc.zip
Expand-Archive $ENV:TEMP\cloudtruth.zip -DestinationPath $ENV:TEMP
copy-item -Path $ENV:Temp\cloudtruth-$CT_CLI_VERSION-x86_64-pc-windows-msvc\* C:\cloudtruth\
$env:Path += ";C:\cloudtruth"

The script will add C:\cloudtruthto your Path for the current PowerShell session. You can either addC:\ cloudtruthto your windows path or execute the CLI directly from C:\cloudtruth.

RedHat/CentOS

Coming Soon!

Configuration

The CloudTruth CLI tool has several ways of configuring it, allowing you to pick whichever method is most suitable for your environment. With any method you will need to create a CloudTruth Access Token to grant the CLI access.

You can configure the CLI using:

Method 1: Environment-based Configuration

The CloudTruth CLI can use supported CLOUDTRUTH_ environment variables that are exported in a local shell. CloudTruth environment variables will merge with and take precedence over a configured CloudTruth configuration file.

Config Options

Usage

CLOUDTRUTH_API_KEY

Required: Authenticates the CLI with the provided CloudTruth API Token

Provide your CloudTruth API Key as an environment variable:

export CLOUDTRUTH_API_KEY="YOUR_API_KEY"

Method 2: Argument-based Configuration

The CloudTruth CLI can be authorized directly by specifying the option --api-key and providing your API key:

cloudtruth --api-key "YOUR_API_KEY"

You can prefix commands with a space " " in order to avoid having secret values like the API Key stored in your shell history.

Method 3: File-based Configuration

The CloudTruth CLI stores its configuration in the YAML format.

Run cloudtruth config edit to initialize and open the configuration in your default editor.

---
profiles:
default:
api_key: <Your personal access token>
another_profile:
source_profile: default
api_key: <Another personal access token>

You can have multiple named profiles in your configuration, allowing you to maintain multiple sets of configuration fields in the configuration file. Values can be inherited from one profile to another by setting the source_profile configuration field. Profiles without an explicit source_profile configuration implicitly inherit from the default profile. Use a specific profile with the --profile option.

cloudtruth --profile another-profile <subcommand>

If the --profile argument is not supplied, the profile named default will be used.

The created configuration file is named cli.yml and resides in the standard application configuration location for your platform:

  • Linux -> $XDG_CONFIG_HOME/cloudtruth/cli.yml

  • macOS -> $HOME/Library/Application Support/com.cloudtruth.CloudTruth-CLI/cli.yml

  • Windows -> %AppData%\CloudTruth\CloudTruth CLI\config\cli.yml

Running

Once you have the application configured with your CloudTruth API key, you can interact with your CloudTruth parameters. The CloudTruth CLI uses a subcommand structure to scope available actions as appropriate for a given resource.

Options

-k, --api-key

CloudTruth API key

-e, --env

The CloudTruth environment to work with

-p, --profile

The profile from the application configuration file to use [default: default]

Flags

-h, --help

Prints help information

-V, --version

Prints version information

Subcommands

completions

Generate shell completions for this application

config

Configuration options for this application [aliases: configuration]

environments

Work with CloudTruth environments [aliases: environment, envs, env, e]

help

Prints this message or the help of the given subcommand(s)

parameters

Work with CloudTruth parameters [aliases: parameter, params, param, p]

run

Run a shell with the parameters in place [aliases: run, r]

templates

Work with CloudTruth templates [aliases: template, t]

CloudTruth run

The CloudTruth run command allows you to dynamically use parameters stored in CloudTruth and pass them through to your applications.

You can issue the cloudtruth run command with printenv to print all of your local and CloudTruth parameters.

cloudtruth run --command printenv

Inheritance

By default the run command will overlay all CloudTruth and local parameters into your command. You can use the --inherit option to change the behavior. This example will only passthrough CloudTruth parameters:

cloudtruth run --inherit none --command printenv

Dynamic run time parameters

The run command will also allow you to remove or set parameters to customize a specific workflow in real time.

cloudtruth run --command printenv -set NEW_VALUE=Production -remove SOME_VALUE=bye

Switching the active CloudTruth Environment

By default, all commands will run against the default CloudTruth environment. To change the target environment, you can supply use--env option:

cloudtruth --env production parameters get my_param

You can also get auto-completions for most popular shells by running:

cloudtruth completions <SHELL>, where "SHELL" is the name of your shell.

Issue Reporting

The CloudTruth CLI is open source. You can report issues and get details on building and developing locally in the CloudTruth CLI repo.