CloudTruth Documentation
Sign InAPIIntegrationsGitHubVisit our website
  • Overview
  • Getting Started
  • Architecture
    • ๐Ÿ”’Security Overview
  • Copilot
  • ๐ŸขOrg management
    • Account Setup
    • Access Control
      • ๐Ÿ”‘API Tokens
      • ๐ŸŒProtecting Projects and Environments
      • ๐Ÿ‘ฅUsers
    • Audit Log
  • ๐Ÿ› ๏ธConfig Management
    • Projects
    • Parameters
      • Sharing Config Data
      • Parameter Management
        • Internal Values
          • Dynamic Values
        • External Values
          • Terraform Remote State Files
        • Parameter Override
        • Environment Value Override
      • Parameter and Parameter Value Inheritance
      • Value Comparison
      • Value History
      • Value Validation
      • Value Expiration
    • Environments and Tags
    • Templates
      • ๐Ÿ“’Sample Templates
    • Actions
      • Import Actions
      • Push Actions
    • CLI & API
      • CloudTruth CLI
      • Rest API
    • Integrations
      • Argo CD
      • Atlassian Compass
      • AWS
        • AWS Connection
        • AWS Role
          • CloudFormation
          • Terrraform
          • AWS Console
        • Parameter Store (SSM)
        • S3
        • Secrets Manager
      • Azure Key Vault
      • Bitbucket Pipelines
      • Docker
      • Docker Compose
      • GitHub
      • GitHub Actions
      • GitLab
      • Harness
      • Jenkins
      • Kubernetes
      • Pulumi
      • Terraform
      • Terragrunt
      • Explorer
      • Circle CI
    • Events, Notifications, Webhooks
    • Types
  • ๐Ÿ”ŽREPORTING
    • Compare
    • History
    • Expirations
  • ๐Ÿš€PRODUCT
    • What is CloudTruth?
    • Interactive Demo
    • Kubernetes
    • Terraform
    • CI/CD Pipeline Configuration
    • Cloud CMDB
    • Secrets Management
    • GitOps
    • Our Manifesto
    • Open Source
    • FAQs
    • Our Mission
  • ๐Ÿ“šReference
    • ๐ŸŽ“Quick Start Videos
      • What is CloudTruth?
      • CloudTruth in Action
      • Environments and Projects
      • Secrets, Parameters, ENV variables
      • Audit Logs, RBAC, SSO
      • Containers - Kubernetes, Docker
      • Infrastructure as Code (IaC) - Terraform, Cloudformation, CDK, Azure Bicep, Pulumi
      • CICD Pipelines - GitHub Actions, ArgoCD, Jenkins, CircleCI, Harness, GitLab Pipelines
      • AWS Videos - Secret Manager, Parameter Store, S3, IAM
      • Azure Videos - Azure DevOps, Azure Bicep, PowerShell
    • Knowledge Base
      • Best Practices
        • Versioned Releases
      • CLI
        • History comparison of deleted parameters with null values
      • Integrations
        • Advanced AWS IAM policy permissions
        • K8s pull image from private Docker registry
        • S3 Region Selection
      • Templates
        • Templates render quotations in key values as quot
    • Roadmap and New Features
    • JMESPath Reference
    • REST API
Powered by GitBook

Copyrightยฉ 2023 CloudTruth

On this page
  • Installation
  • Configuration
  • Method 1: Environment-based Configuration
  • Method 2: Argument-based Configuration
  • Method 3: File-based Configuration
  • Running
  • Switching the active CloudTruth Project and Environment
  • CloudTruth run
  • Usage Examples
  • Command List
  • Issue Reporting

Was this helpful?

  1. Config Management
  2. CLI & API

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.

PreviousCLI & APINextRest API

Last updated 1 year ago

Was this helpful?

Installation

The CLI is available as package with a binary executable. Download the version built for your Platform:

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.

The shell installer supports Linux and Darwin distros and will install the latest version.

  • curl

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

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

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

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

Make sure the Windows execution policy is set to allow running PowerShell scripts.

This script requires or higher, if PowerShell 7 isn't available on your system, use the

Download:

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

Change directories to the download location:

cd $env:TEMP

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

.\install.ps1

or, to install a specific CloudTruth CLI version:

.\install.ps1 -Version <version>

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

Get latest version and download:

CLOUDTRUTH_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/${CLOUDTRUTH_CLI_VERSION}/cloudtruth_${CLOUDTRUTH_CLI_VERSION}_amd64.deb

Install:

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

The installation process on RHEL7/CentOS7 requires CloudTruth CLI v1.2.1 or higher.

Get latest version and download:

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

curl -sLOJ https://github.com/cloudtruth/cloudtruth-cli/releases/download/${CLOUDTRUTH_CLI_VERSION}/cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.aarch64.rpm
  • Intel (x86_64)

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

Install:

  • ARM64 (aarch)

sudo rpm -i cloudtruth-${CLOUDTRUTH_CLI_VERSION}-1.aarch64.rpm
  • Intel (x86_64)

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

Get latest version and download:

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

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

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

Extract:

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

Install:

  • Intel processor:

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

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

Get latest version and download:

$CLOUDTRUTH_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/$CLOUDTRUTH_CLI_VERSION/cloudtruth-$CLOUDTRUTH_CLI_VERSION-x86_64-pc-windows-msvc.zip

Extract to temporary directory:

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

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

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

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

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

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 to grant the CLI access.

You can configure the CLI using:

  • Method 1:

  • Method 2:

  • Method 3:

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"

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"

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.

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

Listing objects such as projects, environments and parameters will return a list of names. For detailed information use the values flag-v, --values.

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

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

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

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

command
subcommand
Description

audit-logs

Display audit logs [aliases: audit, aud, a, log, logs]

list

List audit log details [aliases: ls, l]

summary

Display summary of audit logs [aliases: sum]

completions

Generate shell completions for this application

configuration

Configuration options for this application [aliases: config, conf, con]

current

Show the current arguments and their sources. [aliases: curr, cur]

edit

Edit your configuration data for this application

profiles

Work with CloudTruth CLI profiles [aliases: profile, prof, pr, p]

environments

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

copy

Copy an environment and its children to new environment(s) [aliases: cp]

delete

Delete specified CloudTruth environment [aliases: del, d]

list

List CloudTruth environments [aliases: ls, l]

set

Create/update a CloudTruth environment [aliases: s]

tag

View and manipulate environment tags [aliases: ta]

tree

Show a tree representation of the environments [aliases: tr, t]

help

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

groups

User group management commands

delete

Delete the specified CloudTruth user group

get

Get detailed CloudTruth user group information

list

List CloudTruth user groups

set

Create/update a Cloudtruth user group and manage group users

integrations

Work with CloudTruth integrations [aliases: integration, integrate, integ, int]

explore

Explore integrations by Fully Qualified Name (FQN). [aliases: exp, ex, e]

list

List CloudTruth integrations [aliases: ls, l]

login

Sets up a CloudTruth configuration profile api_key

logout

Removes a CloudTruth configuration profile api_key

parameters

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

copy

Copy a parameter and its value [aliases: cp]

delete

Delete the parameter from the project [aliases: del, d]

differences

Show differences between properties from two environments [aliases: difference, differ, diff]

environment

Shows values across environments [aliases: environ, env]

export

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.

get

Gets value for parameter in the selected environment

list

List CloudTruth parameters [aliases: ls, l]

set

Set a value in the selected project/environment for an existing parameter or creates a new one if needed

unset

Remove a value/override from the selected project/environment and leaves the parameter in place.

projects

Work with CloudTruth projects [aliases: project, proj]

copy

Copy a project and its children to new project(s) [aliases: cp]

delete

Delete specified CloudTruth project [aliases: del, d]

list

List CloudTruth projects [aliases: ls, l]

set

Create/update a CloudTruth project

tree

Display CloudTruth project inheritance [aliases: tr]

run

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

templates

Work with CloudTruth templates [aliases: template, temp, t]

delete

Delete the CloudTruth template [aliases: del, d]

differences

Show differences between templates [aliases: difference, differ, diff, di]

edit

Edit Edit the specified template [aliases: ed, e]

get

Get an evaluated template from CloudTruth

history

Display template history [aliases: hist, h]

list

List CloudTruth templates [aliases: ls, l]

preview

Evaluate the provided template without storing [aliases: prev, pre]

set

Set the CloudTruth template

validate

Validate a CloudTruth template [aliases: valid, val, v]

users

Work with CloudTruth users [aliases: user, us]

current

Display information about current user [aliases: cur, c]

delete

Delete specified CloudTruth account [aliases: del, d]

get

Get detailed CloudTruth user information

invitations

Manage user invitations [aliases: invitation, invite, inv, in, i]

list

List CloudTruth users [aliases: ls, l]

set

Create/update a CloudTruth service account [aliases: s]

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.

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

๐Ÿ› ๏ธ
space
https://github.com/cloudtruth/cloudtruth-cli/releases/latest
PowerShell 7
CloudTruth API Access Token
Windows manual install instructions
Environment variables
Command-line arguments
CloudTruth CLI configuration file
Issues ยท cloudtruth/cloudtruth-cliGitHub
Logo