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

Details

Requirements

Supported OS/Platform:

• GNU/Linux amd6
• MacOs amd64/arm64
• Windows amd64

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 a oneliner to download and make it executable under /usr/local/bin using bash, curl, sudo and jq:

export os="$(uname -s | tr [:upper:] [:lower:])"; \
if [[ "$(uname -m)" == "x86_64" ]]; then export platform=amd64 ; else export platform=arm64 ; fi; \
  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, fish, zsh and powershell.

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

.bashrc

# bash
source <(cy completion bash)

.zshrc

# zsh
source <(cy completion zsh)

For fish, write the file here

# fish
cy completion fish > ~/.config/fish/completions/cy.fish

And for powershell, append the completion content in the $PROFILE

Add-Content $PROFILE "if (Get-Command cy -ErrorAction SilentlyContinue) {
  cy completion powershell | Out-String | Invoke-Expression
}"

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

warning

Try to use the environment variable as much as possible.

This behavior will be deprecated.

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 $) 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_PROJECT	Set the current project (will be overrident by the --project flag)
CY_ENV	Set the current environment (will be overrident by the --env flag)
CY_COMPONENT	Set the current component (will be overrident by the --component flag)
CY_API_KEY	Set the current API key
CY_VERBOSITY	Set the verbosity level (debug, info, warning, error), default warning

Command list

Usage:
  cy [command]

Available Commands:
  api-key            Manage organization API keys
  beta               Experimental commands.
  catalog-repository Manage the catalog repositories
  completion         Output shell completion for the given shell (bash or zsh)
  components         Manage components.
  config-repository  Manage the catalog repositories
  credential         Manage the credentials
  environment        Manage the environments of a project.
  event              Manage the events
  external-backend   manage external backends
  help               Help about any command
  infrapolicy        Manage the infraPolicies
  kpi                Manage the kpis
  login              Login against the Cycloid console
  members            Manage members from the organization
  organization       Manage the organizations
  pipeline           Manage the pipelines
  project            Manage the projects
  roles              Manage roles from the organization
  stack              Manage the stacks
  status             Get the status of the Cycloid services
  terracost          Use terracost feature
  version            Get the version of the consumed API

Flags:
      --api-url string     Specify the HTTP url of Cycloid API to use eg https://http-api.cycloid.io. This can also be given by CY_API_URL environment variable. (default "https://http-api.cycloid.io")
  -h, --help               help for cy
      --insecure           Decide to skip or not TLS verification
      --org string         Specify the org to use. override CY_ORG env var. Required for all Org scoped endpoint.
  -o, --output string      The formatting style for command output: json|yaml|table (default "table")
  -v, --verbosity string   Override the default verbosity for this command. VERBOSITY must be one of: debug, info, warning, error, critical, none. (default "warning")
      --version            version for cy

Use "cy [command] --help" for more information about a command.