# CloudTruth CLI

## 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/latest>

Here are some examples on how to install the latest version of the CloudTruth CLI on your preferred distribution. The Shell Install command (preferred) will automatically detect your distribution and architecture to install the correct CloudTruth CLI installation package.

{% tabs %}
{% tab title="Shell  (preferred)" %}
The shell installer supports Linux and Darwin distros and will install the latest version.

* curl

{% code overflow="wrap" %}

```
curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sudo sh
```

{% endcode %}

* wget

{% code overflow="wrap" %}

```
wget -qO- https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sudo sh
```

{% endcode %}

You can also specify a version by passing the --version parameter from stdin (curl example).

{% code overflow="wrap" %}

```
curl -sL https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.sh | sudo sh -s -- --version 1.2.0
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell (preferred)" %}
{% hint style="info" %}
Make sure the Windows execution policy is set to allow running PowerShell scripts.
{% endhint %}

{% hint style="warning" %}
This script requires [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) or higher, if PowerShell 7 isn't available on your system, use the [Windows manual install instructions](#windows)
{% endhint %}

Download:

{% code overflow="wrap" %}

```
Invoke-WebRequest https://github.com/cloudtruth/cloudtruth-cli/releases/latest/download/install.ps1 -OutFile $env:TEMP\install.ps1
```

{% endcode %}

Change directories to the download location:

{% code overflow="wrap" %}

```
cd $env:TEMP
```

{% endcode %}

Running the CloudTruth PowerShell  installation script without parameters will install the latest version of the CloudTruth CLI:

{% code overflow="wrap" %}

```
.\install.ps1
```

{% endcode %}

or, to install a specific CloudTruth CLI version:

{% code overflow="wrap" %}

```
.\install.ps1 -Version <version>
```

{% endcode %}

The script will output the executable location to the console, feel free to copy it to a desired location or add the displayed location to the `$env:PATH`
{% endtab %}

{% tab title="Debian/Ubuntu" %}
Get latest version and download:

{% code overflow="wrap" %}

```
CLOUDTRUTH_CLI_VERSION=$(curl --silent "https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest" | grep "tag_name" | sed -E 's/.*"([^"]+)".*/\1/')
```

{% endcode %}

{% code overflow="wrap" %}

```
curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/${CLOUDTRUTH_CLI_VERSION}/cloudtruth_${CLOUDTRUTH_CLI_VERSION}_amd64.deb
```

{% endcode %}

Install:

{% code overflow="wrap" %}

```
sudo dpkg -i cloudtruth_${CLOUDTRUTH_CLI_VERSION}_amd64.deb
```

{% endcode %}
{% endtab %}

{% tab title="RHEL" %}
{% hint style="warning" %}
The installation process on RHEL7/CentOS7 requires CloudTruth CLI v1.2.1 or higher.
{% endhint %}

Get latest version and download:

{% code overflow="wrap" %}

```
CLOUDTRUTH_CLI_VERSION=$(curl --silent "https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest" | grep "tag_name" | sed -E 's/.*"([^"]+)".*/\1/')
```

{% endcode %}

* ARM64 (aarch)

{% code overflow="wrap" %}

```
curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/${CLOUDTRUTH_CLI_VERSION}/cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.aarch64.rpm
```

{% endcode %}

* Intel (x86\_64)

{% code overflow="wrap" %}

```
curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/${CLOUDTRUTH_CLI_VERSION}/cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.x86_64.rpm
```

{% endcode %}

Install:

* ARM64 (aarch)

{% code overflow="wrap" %}

```
sudo rpm -i cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.aarch64.rpm
```

{% endcode %}

* Intel (x86\_64)

```
sudo rpm -i cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.x86_64.rpm
```

{% endtab %}

{% tab title="MacOS" %}
Get latest version and download:

{% code overflow="wrap" %}

```
export CLOUDTRUTH_CLI_VERSION=$(curl --silent "https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest" | grep "tag_name" | sed -E 's/.*"([^"]+)".*/\1/')
```

{% endcode %}

* Intel processor:

{% code overflow="wrap" %}

```
curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/$CLOUDTRUTH_CLI_VERSION/cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-apple-darwin.tar.gz
```

{% endcode %}

* Apple Silicon:

{% code overflow="wrap" %}

```
curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/$CLOUDTRUTH_CLI_VERSION/cloudtruth-$CLOUDTRUTH_CLI_VERSION-aarch64-apple-darwin.tar.gz
```

{% endcode %}

Extract:

{% code overflow="wrap" %}

```
tar xzf cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-apple-darwin.tar.gz
```

{% endcode %}

Install:

* Intel processor:

{% code overflow="wrap" %}

```
sudo install -m 755 -o root "cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-apple-darwin/cloudtruth" /usr/local/bin
```

{% endcode %}

* Apple Silicon

{% code overflow="wrap" %}

```
sudo install -m 755 -o root "cloudtruth-$CLOUDTRUTH_CLI_VERSION-aarch64-apple-darwin/cloudtruth" /usr/local/bin
```

{% endcode %}
{% endtab %}

{% tab title="Windows" %}
Get latest version and download:

{% code overflow="wrap" %}

```
$CLOUDTRUTH_CLI_VERSION = ((Invoke-WebRequest https://api.github.com/repos/cloudtruth/cloudtruth-cli/releases/latest).Content | ConvertFrom-Json).tag_name
```

{% endcode %}

{% code overflow="wrap" %}

```
Invoke-WebRequest -outfile $ENV:TEMP\cloudtruth.zip https://github.com/cloudtruth/cloudtruth-cli/releases/download/$CLOUDTRUTH_CLI_VERSION/cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-pc-windows-msvc.zip
```

{% endcode %}

Extract to temporary directory:

{% code overflow="wrap" %}

```
Expand-Archive $ENV:TEMP\cloudtruth.zip -DestinationPath $ENV:TEMP
```

{% endcode %}

Copy the executable (this example uses `C:\cloudtruth`)

{% code overflow="wrap" %}

```
copy-item -Path $ENV:Temp\cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-pc-windows-msvc\* C:\cloudtruth\
```

{% endcode %}

Add the executable's location to the search path environment variable:

{% code overflow="wrap" %}

```
$env:Path += ";C:\cloudtruth"
```

{% endcode %}
{% endtab %}
{% endtabs %}

## 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 API Access Token](https://docs.cloudtruth.com/org-management/access-control/access-tokens) to grant the CLI access.

You can configure the CLI using:

* Method 1: [Environment variables](#environment-based-configuration)
* Method 2: [Command-line arguments](#argument-base-configuration)
* Method 3: [CloudTruth CLI configuration file](#file-based-configuration)

### 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. |
| `CLOUDTRUTH_PROFILE`     | Your profile (which can contain API key, project, and environment)      |
| `CLOUDTRUTH_PROJECT`     | Sets the targeted project.                                              |
| `CLOUDTRUTH_ENVIRONMENT` | Sets the targeted environment.                                          |

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"
```

{% hint style="warning" %}
You can prefix commands with a [space](https://www.linuxjournal.com/content/using-bash-history-more-efficiently-histcontrol) `" "` in order to avoid having secret values like the API Key stored in your shell history.
{% endhint %}

### Method 3: File-based Configuration

The CloudTruth CLI stores its configuration in the YAML format.

Run `cloudtruth configuration 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>
    project: "Project1"
    environment: "staging"
```

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.

Alternatively, you can use the `cloudtruth configuration profiles` command to create or edit profiles.

```
cloudtruth configuration profiles set default --api-key "YOUR_API_KEY"

cloudtruth configuration profiles set demo-stage --proj MyFirstProject --env staging --desc "Demo Project Staging Environment"
```

{% hint style="info" %}
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
  {% endhint %}

## 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.

### Switching the active CloudTruth Project and Environment

#### CloudTruth Project

You must select a target project for the CLI with the `--project` option:

```
cloudtruth --project YOUR_PROJECT
```

#### 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 --project MyFirstProject --env YOUR_ENVIRONMENT
```

### CloudTruth run

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

| run options   | Description                                                                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| -c, --command | Run this command                                                                                                                             |
| --as-of       | Date/time of parameter value(s)                                                                                                              |
| -i, --inherit | Handle the relationship between local and CloudTruth environments \[default: overlay] \[possible values: none, underlay, overlay, exclusive] |
| r, --remove   | Remove the variables from the CloudTruth environment for this run                                                                            |
| -s, --set     | Set the variables in this run, even possibly overriding the CloudTruth environment                                                           |

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

```
cloudtruth --project MyFirstProject 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 --project MyFirstProject run --inherit none --command printenv
```

#### Run time parameters

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

```
cloudtruth --project MyFirstProject run --inherit none --command printenv --set NEW_VALUE=Production --remove SOME_VALUE
```

### Usage Examples

{% hint style="success" %}
Listing objects such as projects, environments and parameters will return a list of names. For detailed information use the values flag`-v, --values`.
{% endhint %}

Create a new parameter and set a value. To mark the value as a secret use the `--secret` flag.

```
cloudtruth --project MyFirstProject parameters set PARAMETER_KEY --value SOME_VALUE 
```

View a list of all parameters with values.

```
cloudtruth --project MyFirstProject parameters list --values
```

Retrieve a specific parameter value by key name

```
cloudtruth --project MyFirstProject parameter get PARAMETER_KEY
```

Retrieve overrides for specific parameter values across environments.

```
cloudtruth --project MyFirstProject parameter environment PARAMETER_KEY
```

Show differences with parameter values across two environments.

```
cloudtruth --project MyFirstProject parameter differences --env staging --env  production
```

View a tree view of all environments.

```
cloudtruth --project MyFirstProject environments tree
```

Retrieve the contents of a project template.

```
cloudtruth --project MyFirstProject template get "TEMPLATE_NAME"
```

### Command List

{% hint style="success" %}
You can also get auto-completions for most popular shells by running:

`source <(cloudtruth completions <SHELL>),` where "SHELL" is the name of your shell.
{% endhint %}

| Flags         | Description                |
| ------------- | -------------------------- |
| -h, --help    | Prints help information    |
| -V, --version | Prints version information |

| Options       | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| -k, --api-key | CloudTruth API key                                                       |
| -e, --env     | The CloudTruth environment to work with                                  |
| --profile     | The configuration profile from the application configuration file to use |
| --project     | The CloudTruth project to work with                                      |

<table data-full-width="false"><thead><tr><th>command</th><th>subcommand</th><th>Description</th></tr></thead><tbody><tr><td>audit-logs</td><td></td><td>Display audit logs [aliases: audit, aud, a, log, logs]</td></tr><tr><td></td><td>list</td><td>List audit log details [aliases: ls, l]</td></tr><tr><td></td><td>summary</td><td>Display summary of audit logs [aliases: sum]</td></tr><tr><td>completions</td><td></td><td>Generate shell completions for this application</td></tr><tr><td>configuration</td><td></td><td>Configuration options for this application [aliases: config, conf, con]</td></tr><tr><td></td><td>current</td><td>Show the current arguments and their sources. [aliases: curr, cur]</td></tr><tr><td></td><td>edit</td><td>Edit your configuration data for this application</td></tr><tr><td></td><td>profiles</td><td>Work with CloudTruth CLI profiles [aliases: profile, prof, pr, p]</td></tr><tr><td>environments</td><td></td><td>Work with CloudTruth environments [aliases: environment, envs, env, e]</td></tr><tr><td></td><td>copy</td><td>Copy an environment and its children to new environment(s) [aliases: cp]</td></tr><tr><td></td><td>delete</td><td>Delete specified CloudTruth environment [aliases: del, d]</td></tr><tr><td></td><td>list</td><td>List CloudTruth environments [aliases: ls, l]</td></tr><tr><td></td><td>set</td><td>Create/update a CloudTruth environment [aliases: s]</td></tr><tr><td></td><td>tag</td><td>View and manipulate environment tags [aliases: ta]</td></tr><tr><td></td><td>tree</td><td>Show a tree representation of the environments [aliases: tr, t]</td></tr><tr><td>help</td><td></td><td>Prints this message or the help of the given subcommand(s)</td></tr><tr><td>groups</td><td></td><td>User group management commands</td></tr><tr><td></td><td>delete</td><td>Delete the specified CloudTruth user group</td></tr><tr><td></td><td>get</td><td>Get detailed CloudTruth user group information</td></tr><tr><td></td><td>list</td><td>List CloudTruth user groups</td></tr><tr><td></td><td>set</td><td>Create/update a Cloudtruth user group and manage group users</td></tr><tr><td>integrations</td><td></td><td>Work with CloudTruth integrations [aliases: integration, integrate, integ, int]</td></tr><tr><td></td><td>explore</td><td>Explore integrations by Fully Qualified Name (FQN). [aliases: exp, ex, e]</td></tr><tr><td></td><td>list</td><td>List CloudTruth integrations [aliases: ls, l]</td></tr><tr><td>login</td><td></td><td>Sets up a CloudTruth configuration profile api_key</td></tr><tr><td>logout</td><td></td><td>Removes a CloudTruth configuration profile api_key</td></tr><tr><td>parameters</td><td></td><td>Work with CloudTruth parameters [aliases: parameter, params, param, p]</td></tr><tr><td></td><td>copy</td><td>Copy a parameter and its value [aliases: cp]</td></tr><tr><td></td><td>delete</td><td>Delete the parameter from the project [aliases: del, d]</td></tr><tr><td></td><td>differences</td><td>Show differences between properties from two environments [aliases: difference, differ, diff]</td></tr><tr><td></td><td>environment</td><td>Shows values across environments [aliases: environ, env]</td></tr><tr><td></td><td>export</td><td>Export selected parameters to a known output format. Exported parameters are limited to alphanumeric and underscore in key names. Formats available are: dotenv, docker, and shell.</td></tr><tr><td></td><td>get</td><td>Gets value for parameter in the selected environment</td></tr><tr><td></td><td>list</td><td>List CloudTruth parameters [aliases: ls, l]</td></tr><tr><td></td><td>set</td><td>Set a value in the selected project/environment for an existing parameter or creates a new one if needed</td></tr><tr><td></td><td>unset</td><td>Remove a value/override from the selected project/environment and leaves the parameter in place.</td></tr><tr><td>projects</td><td></td><td>Work with CloudTruth projects [aliases: project, proj]</td></tr><tr><td></td><td>copy</td><td>Copy a project and its children to new project(s) [aliases: cp]</td></tr><tr><td></td><td>delete</td><td>Delete specified CloudTruth project [aliases: del, d]</td></tr><tr><td></td><td>list</td><td>List CloudTruth projects [aliases: ls, l]</td></tr><tr><td></td><td>set</td><td>Create/update a CloudTruth project</td></tr><tr><td></td><td>tree</td><td>Display CloudTruth project inheritance [aliases: tr]</td></tr><tr><td>run</td><td></td><td>Run a shell with the parameters in place [aliases: run, r]</td></tr><tr><td>templates</td><td></td><td>Work with CloudTruth templates [aliases: template, temp, t]</td></tr><tr><td></td><td>delete</td><td>Delete the CloudTruth template [aliases: del, d]</td></tr><tr><td></td><td>differences</td><td>Show differences between templates [aliases: difference, differ, diff, di]</td></tr><tr><td></td><td>edit</td><td>Edit Edit the specified template [aliases: ed, e]</td></tr><tr><td></td><td>get</td><td>Get an evaluated template from CloudTruth</td></tr><tr><td></td><td>history</td><td>Display template history [aliases: hist, h]</td></tr><tr><td></td><td>list</td><td>List CloudTruth templates [aliases: ls, l]</td></tr><tr><td></td><td>preview</td><td>Evaluate the provided template without storing [aliases: prev, pre]</td></tr><tr><td></td><td>set</td><td>Set the CloudTruth template</td></tr><tr><td></td><td>validate</td><td>Validate a CloudTruth template [aliases: valid, val, v]</td></tr><tr><td>users</td><td></td><td>Work with CloudTruth users [aliases: user, us]</td></tr><tr><td></td><td>current</td><td>Display information about current user [aliases: cur, c]</td></tr><tr><td></td><td>delete</td><td>Delete specified CloudTruth account [aliases: del, d]</td></tr><tr><td></td><td>get</td><td>Get detailed CloudTruth user information</td></tr><tr><td></td><td>invitations</td><td>Manage user invitations [aliases: invitation, invite, inv, in, i]</td></tr><tr><td></td><td>list</td><td>List CloudTruth users [aliases: ls, l]</td></tr><tr><td></td><td>set</td><td>Create/update a CloudTruth service account [aliases: s]</td></tr></tbody></table>

## 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.

{% embed url="<https://github.com/cloudtruth/cloudtruth-cli/issues>" %}