Skip to content

Coherence CLI (cocli)

Introduction

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 the installation and usage of cocli, with a focus on the toolbox functionality.

Table of Contents

  1. Installation
  2. Authentication
  3. Basic Usage
  4. Advanced Usage
  5. Deployment from CI example
  6. Managing Environent Variables
  7. Troubleshooting

Installation

cocli is an open-source go program that's easy to install and use. To get started with cocli, install it:

Authentication

Before using cocli, you need to authenticate:

  1. Create an access token in your Coherence user profile (top right user menu).
  2. 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 UI. Always store your token securely.

Basic Usage

Here are some basic commands to get you 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 info from the json responses the API will return.

Get help for a specific command

cocli <command> --help

Cocli allows you to perform complex operations, including:

  • Managing application deployments
  • Configuring environments
  • Monitoring application status

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

Advanced Usage

cocli -c COLLECTION_ID cnc is able to perform the complete build and deploy suite of commands from cnc. Due to terraform state management conflict potential, we don't yet support running provision outside Coherence using the cocli wrapper for cnc. The wrapper is powerful since it dynamically generates the cnc.yml and environments.yml for cnc use based on the Coherence system's configuration, allowing you to use the UI, CLI, and GitHub integration in order to power your cnc configuration.

  • The most common use case for the cnc wrapper is to use a toolbox or start the local access proxy to cloud resources for an environment with --proxy-only in the toolbox command.
  • Another powerful option is to deploy uncomitted code to an environment, since cnc will deploy the code in the context it is run, and won't trigger a GitHub based build like cocli environment deploy would.

Deploy Example

Coherence can be set to auto-deploy each commit on a branch, in which case no CLI actions are needed. But for users who wish to control their deployments in conjunction with other actions such as running tests or manual approvals in another system, there are 2 options:

  • You can use the New Build action on each environment in the Coherence UI in order to deploy whatever code you want for each service in the environment
  • You can use cocli in your CI/CD pipeline to automate deployments. Here's an example of how to deploy an environment using GitHub Actions

Here's an example of using cocli in GitHub Actions in order to deploy to an environment in Coherence.

  1. First, store your Coherence access token as a GitHub secret named COHERENCE_ACCESS_TOKEN in your repository settings.
  2. 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 application ID
        APP_ID=$(cocli apps list | jq -r '.[] | select(.title=="Your App Name") | .id')

        # Get the collection ID
        COLLECTION_ID=$(cocli collections list -a $APP_ID | jq -r '.data[] | select(.name=="production") | .id')

        # Get the environment ID
        ENV_ID=$(cocli environments list -c $COLLECTION_ID | jq -r '.data[] | select(.name=="main") | .id')

        # Deploy to the environment
        cocli environments deploy $ENV_ID '{
          "services": [
            {
              "name": "your-service-name",
              "branch_name": "main",
              "commit_sha": "${{ github.sha }}"
            }
          ],
          "configure_infra": false
        }'

To make this example work in the real world:

  • Replace Your App Name as the app name, production as the collection name, and main as the environment name with the appropriate values for your application. You can also 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.
  • Use a different branch and service name as appropriate in the deploy payload.

You can run this as a standalone workflow or as part of an existing workflow, as fits your needs.

Environment Variables

Coherence CLI (cocli) provides several commands to manage environment variables for your applications. These commands allow you to list, create, update, and delete environment variables across your environments and collections.

Listing Environment Variables

To 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 will display both regular environment variables and managed environment variables.

Creating Environment Variables

To 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 of the environment variable (required)
  • --type: Type of the environment variable (standard, secret, output, or alias)
  • --value: Value of the environment variable
  • --collection_id or --environment_id: Specify where to create the variable
  • --service_name: Name of the service (if applicable)
  • --secret_id: ID of the secret (for secret type)
  • --output_name: Name of the output (for output type)
  • --alias: Alias (for alias type)

Bulk Upserting Environment Variables

To 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: Name of the service (if applicable)
  • --type: Type of the environment variables (standard or secret)
  • --file: Path to the .env file
  • --env-string: String representation of environment variables

Getting Environment Variable Value

To retrieve the value of a specific environment variable:

cocli env-vars get-value <environment_item_id>

Deleting Environment Variables

To 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 the version of cocli that you are using and ensure you're up to date.
  • Ensure your access token is correctly set and not 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 the Coherence support team (support@withcoherence.com).