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 amd64/arm64
• 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 --arg asset "cy-$os-$platform" '.assets[] | select(.name==$asset) | .browser_download_url') \
    && chmod +x "cy-$os-$platform" \
    && sudo mkdir -p /usr/local/bin \
    && sudo mv "cy-$os-$platform" /usr/local/bin/cy

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

Authentication

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-toolkit
          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-toolkit
          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_CONSOLE_URL	Override the Cycloid console base URL used for build deep links, default https://console.cycloid.io
CY_ORG	Set the current organization (will be overridden by the --org flag)
CY_PROJECT	Set the current project (will be overridden by the --project flag)
CY_ENV	Set the current environment (will be overridden by the --env flag)
CY_COMPONENT	Set the current component (will be overridden by the --component flag)
CY_API_KEY	Set the current API key
CY_OUTPUT	Set the default output format (table, json, yaml, table:border, ...), will be overridden by the --output flag
CY_VERBOSITY	Set the verbosity level (debug, info, warning, error), default warning. debug prints every HTTP request and response to stderr, including headers and bodies — the output contains credentials (the API key is truncated to its last 5 characters)
HTTP_PROXY	Set the http proxy with host[:port] format for http requests
HTTPS_PROXY	Set the https proxy with host[:port] format for https requests
NO_PROXY	List of hosts that must bypass the proxy configuration

Command list

Usage:
  cy [command]

Available Commands:
  api-key            Manage organization API keys
  beta               Experimental commands.
  catalog-repository Manage the catalog repositories
  cloud-account      Manage cloud accounts
  completion         Output shell completion for the given shell (bash or zsh)
  components         Manage components.
  config-repository  Manage the config repositories
  credential         Manage the credentials
  environment        Manage organization environments.
  environment-type   Manage environment types
  event              Manage the events
  external-backend   manage external backends
  get                Get Cycloid resources by using its URI
  help               Help about any command
  inventory          Manage the inventory
  kpi                Manage the kpis
  login              Login against the Cycloid console
  members            Manage members from the organization
  oidc               Manage OIDC group mappings and settings
  organization       Manage the organizations
  output             Manage the default output format
  pipeline           Manage the pipelines
  plugin             Manage plugins
  project            Manage the projects
  roles              Manage roles from the organization
  stack              Manage the stacks
  status             Get the status of the Cycloid services
  teams              Commands to manage teams
  terracost          Use terracost feature
  uri                Use URI schemes with Cycloid
  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
      --jq string          Shorthand for --output jq=<expr>. Runs a jq expression over the full JSON response.
      --org string         Specify the org to use. override CY_ORG env var. Required for all Org scoped endpoint.
  -o, --output string      Output format: table, table=col1,col2, table:noheader, table:border, json, yaml, jq=<expr>, <field>. Use --jq as shorthand for jq=<expr>. (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.