Cycloid CLI

Introduction

If you are a user of Cycloid and want to push automation a little bit further by playing with our Cycloid API, the Cycloid CLI is here for you.

Here at Cycloid, our DevOps team is using it almost every day to perform routine tasks, technical demonstrations for new customers, or even to send events to the Cycloid console.

The Cycloid CLI is one of our Open Source projects. If you want to contribute to it, you can check out the code on our Github repository.

Installation

Requirements

• A GNU/Linux distribution.

Precompiled binaries for released versions are available in the release page on Github. Using the latest production release binary is the recommended way of installing the Cycloid CLI.

tip

Here is oneliner to download and make it executable under /usr/local/bin using curl and jq:

curl -sLO $(curl -s https://api.github.com/repos/cycloidio/cycloid-cli/releases/latest | jq -r '.assets[] | select(.name=="cy") | .browser_download_url') \
  && chmod +x cy \
  && sudo mkdir -p /usr/local/bin \
  && sudo mv cy /usr/local/bin

Setup completion

Completion is available for bash and zsh shells.

Add the required line to your .bashrc or .zshrc file.

# bash
source <(cy completion bash)
# zsh
source <(cy completion zsh)

Quickstart

Authentification

Cycloid CLI uses Cycloid API Keys to authenticate with at least organization::read authorization.

tip

You can generate an API key in the Security->API Keys section on the console.

Two login methods are available:

Env var

You can set the CY_API_KEY environment variable and every command will use it.

Usage in pipeline

jobs:
- name: "use cy cli"
  plan:
  - do:
    - task: "use cy cli"
      config:
        platform: "linux"
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-tookit
          tag: latest
      params:
        CY_API_KEY: ((your_api_key_credential))
      run:
        path: "/bin/bash"
        args:
        - -exc
        - |
          # Use any cycloid command here

Login

note

Try to use the environment variable as much as possible.

A cy login will write your API key in your $HOME/.cycloid folder.

To login to Cycloid with the CLI run:

cy login --org <your_org> --api-key <your_api_key>

warning

Use an environment variable to avoid putting your API key in your command line history.

You can login to as many orgs as you like, each org will be scoped by the cy --org flag.

Usage in pipeline

warning

In a pipeline, it is recommended to use the environment variable.

Inside a Cycloid pipeline, you can use cycloid credentials to pass the API key.

jobs:
- name: "use cy cli"
  plan:
  - do:
    - task: "use cy cli"
      config:
        platform: "linux"
      image_resource:
        type: registry-image
        source:
          repository: cycloid/cycloid-tookit
          tag: latest
      run:
        path: "/bin/bash"
        args:
        - -exc
        - |
          cy --org ($ organization_canonical $) login --api-key ((your_api_key_credential))

Environment variables

You can use the following environment variables to configure your CLI:

name	description
CY_API_URL	Specify the HTTP url of Cycloid API to use, default https://http-api.cycloid.io, you can use the special variable ($ .api_url $) to point to the current console API URL.
CY_ORG	Set the current organization (will be overrident by the --org flag)
CY_API_TOKEN	Set the current API TOKEN
CY_VERBOSITY	Set the verbosity level (debug, info, warning, error), default warning

Examples

Validate stackforms

The Cycloid CLI can be used to validate stackforms files.

This is very useful for stack creators, it is a more convenient way to check the validity of your stack.

The .forms.yml must be in the current directory

cy --org <your_org> stack validate-form

Output result in JSON

Use the --output json flag to output the result in JSON format.

cy --org <your_org> project list -o json | jq -r .

Credentials management

Lookup the manage credentials using the CLI section.

Create a catalog repository

note

You will need to provide a valid SSH credential canonical for the git repo you want to use.

cy --org <your_org> catalog-repository create \
	--branch <catalog_branc> --cred <git_ssh_credential> \
	--url <you_git_catalog_repo> --name "my_catalog_repo"

Delete a catalog repository

warning

All project using a stack inside the repository must be deleted before the repository can be deleted.

cy --org <your_org> catalog-repository delete --canonical <catalog_repo_canonical>

Create a config repository

note

You will need to provide a valid SSH credential canonical for the git repo you want to use.

cy --org <your_org> catalog-repository create \
	--branch <catalog_branc> --cred <git_ssh_credential> \
	--url <you_git_catalog_repo> --name "my_config_repo" \
  --default # Add the default flag if you want to set this repository as default config repository for the current org

Create an environment using stackforms

$ cy projects create-stackforms-env --org myOrg \
  -p myProject -e myNewEnv \
  -u stack-usecase \
  --var-file /path/to/json/var/file \
  --json-vars '{"section": {"group": {"myVar": "foo" }}}'

The output will be the new environment configuration as understood by the backend.

Read environment config (require stack using stackforms)

This command allows you to fetch the current config of an environement using stackforms.

$ cy --org myOrg project get-env myProject myEnv
{
  "section": {
    "group": {
      "var": "foo"
    }
  }
}

The output format matches the input format for cy project create-stackforms-env, allowing you to easily duplicate an environment by piping the output.

$ cy --org myOrg project get-env myProject env1 \
  | cy --org myOrg \
    -p myProject -e myNewEnv \
    -u stack-usecase \
    --var-file "-" # if '-' is given as filename, this will read from stdin