Coherence CLI (cocli)

Introduction

The Coherence CLI (cocli) is a powerful command-line tool designed to interact with the Coherence API, allowing you to manage your applications and perform various tasks. This guide covers how to install and use cocli, focusing on the toolbox functionality.

Installation

The Coherence CLI is an open-source Go program that is easy to install and use.

Install cocli by following the instructions in the cocli GitHub repository.

Authentication

You will need a personal access token to authenticate your cocli before you can use it:

Create an access token in your Coherence user profile:
- Click the three-dot menu in the top-right corner of the Coherence dashboard and select Profile from the dropdown.
- In the API section of your Profile, click Create token.

Set the token in your shell:

export COHERENCE_ACCESS_TOKEN="your-access-token-here"

Note: Tokens can be set to expire and can be managed through the Coherence UI. Always store your token securely.

Basic use

Use the following basic commands to get started with cocli:

# List all your applications
cocli apps list

# List collections for a specific application
cocli collections list -a <app_id>

You can use jq in conjunction with cocli to get information from the json responses that the Coherence API returns.

For example, you can use jq to:

Get your application ID

cocli apps list | jq '.data[] | select(.name == "APP_NAME")'

Get your collection ID

cocli collections list --app_id APPID | jq '.data[] | select(.name == "COLLECTION_NAME")'

Get your environment ID

cocli collections list --app_id APPID | jq '.data[] | select(.name == "COLLECTION_NAME") | .latest_infra_config.valid_environments[] | select(.name == "ENVIRONMENT_NAME") | .id

Get help for a specific command

cocli <command> --help

The Coherence CLI allows you to perform complex operations, such as:

Managing application deployments
Configuring environments
Monitoring application status

For detailed information about using these advanced features, refer to the cocli GitHub repository.

Advanced use

You can use cocli -c COLLECTION_ID cnc to perform the complete build and deploy suite of commands from CNC.

Due to the conflict potential of terraform state management, we don't yet support the use of the cocli wrapper to run provision outside Coherence.

The cocli wrapper is powerful because it dynamically generates the cnc.yml and environments.yml for use with CNC, based on the Coherence system's configuration. This allows you to use the UI, CLI, and GitHub integrations to power your CNC configuration.

Common use cases for the wrapper include running the CNC toolbox or using the --proxy-only toolbox command to start a local access proxy to the cloud resources for an environment.
You can also use the wrapper to deploy uncommitted code to an environment, as CNC will deploy the code in the context it is run, without triggering a GitHub-based build like cocli environment deploy would.

Deploy example

Coherence can be set to automatically deploy each commit on a branch, in which case no CLI actions are needed.

However, if you wish to control your deployments in conjunction with other actions, such as running tests or manual approvals in another system, you have two options:

You can use the Coherence UI to deploy the code you want for each service by clicking New deployment in the Deployments tab of the environment homepage.
You can use cocli in your CI/CD pipeline to automate deployments.

The following example demonstrates how to deploy an environment using GitHub Actions:

First, store your Coherence access token as a GitHub secret, named COHERENCE_ACCESS_TOKEN, in your repository settings.

Create a file, named .github/workflows/deploy.yml, in your repository with the following content:

name: Deploy to Coherence

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    - name: Install cocli
      run: |
        curl -L https://github.com/coherenceplatform/cocli/releases/latest/download/cocli-linux-amd64 -o cocli
        chmod +x cocli
        sudo mv cocli /usr/local/bin/

    - name: Deploy to Coherence
      env:
        COHERENCE_ACCESS_TOKEN: ${{ secrets.COHERENCE_ACCESS_TOKEN }}
      run: |
        # Get the environment ID from Coherence, see below
        # Deploy to the environment
        cocli environments deploy $ENV_ID '{
          "services": [
            {
              "name": "your-service-name",
              "branch_name": "main",
              "commit_sha": "${{ github.sha }}"
            }
          ],
          "configure_infra": false
        }'

Run this as a standalone workflow or as part of an existing workflow, according to your needs.

YAML script notes:

You can get the environment ID from the URL in the Coherence UI and hard-code it in your script.
In the URL beta.withcoherence.com/apps/my-app/my-collection/1, 1 is the environment ID.

If you want to get the ID of an environment using cocli, the best approach is as follows:

cocli collections list --app_id APPID | jq '.data[] | select(.name == "COLLECTION_NAME") | .latest_infra_config.valid_environments[] | select(.name == "ENVIRONMENT_NAME") | .id'

Use a different branch and service name as appropriate in the deploy payload.
If you are deploying a service that uses an existing image instead of building from a repo, the commit_sha will be used as the image tag, and the branch_name will be ignored (since the system doesn't need to clone the repo to build an image).

Environment variables

The Coherence CLI provides several commands for managing the environment variables of your applications. You can use the following commands to list, create, update, or delete environment variables across your environments and collections:

List environment variables for a specific environment or collection

# List environment variables for an environment
cocli env-vars list --environment_id <environment_id>

# List environment variables for a collection
cocli env-vars list --collection_id <collection_id>

This command displays both regular environment variables and managed environment variables.
Create a new environment variable

cocli env-vars create --target_env_name <variable_name> --type <variable_type> --value <variable_value> [--collection_id <collection_id> | --environment_id <environment_id>] [--service_name <service_name>]

Options:

--target_env_name: Name the environment variable (required).
--type: Specify the type of environment variable (standard, secret, output, or alias).
--value: Enter the value of the environment variable.
--collection_id or --environment_id: Specify where to create the variable.
--service_name: Enter the name of the service (if applicable).
--secret_id: Enter the ID of the secret (for secret type).
--output_name: Enter the name of the output (for output type).
--alias: Specify the alias (for alias type).
Bulk upsert environment variables from a .env file or a string representation

cocli env-vars upsert [--collection_id <collection_id> | --environment_id <environment_id>] [--service_name <service_name>] --type <variable_type> [--file <path_to_env_file> | --env-string <env_string>]

Options:

--collection_id or --environment_id: Specify where to upsert the variables.
--service_name: Enter the name of the service (if applicable).
--type: Specify the type of environment variables (standard or secret).
--file: Specify the path to the ENV file.
--env-string: Enter the string representation of the environment variables.
Get the value of a specific environment variable

cocli env-vars get-value <environment_item_id>

Delete an environment variable

cocli env-vars delete <environment_item_id>

These commands provide a comprehensive set of tools for managing environment variables through the Coherence CLI. You can use them to streamline your workflow and integrate environment variable management into your CI/CD pipelines or development processes.

Troubleshooting

If you encounter issues:

Check which version of cocli you're using and update it if necessary.
Ensure your access token has been set correctly and hasn't expired.
Check your network connection to the Coherence API.
Use the --debug flag with cocli commands for more detailed output.
Consult the Coherence documentation for more information.
Use the --help flag with any command for more detailed information about its usage and options.

For additional support, contact Coherence Support.