Overview

Comprehensive automation can be quickly developed by using the RCTL Command Line Interface (RCTL) utility. RCTL enables users to script and automate reproducible workflows without having to interact with the Controller via the Web Console or the APIs or the Terraform provider.

Explore our blog for deeper insights on Declarative Cluster Lifecycle Management, available here!

Scope¶

The RCTL CLI can be embedded into your preferred "workflow automation platform" and be used to perform operations on ALL resources managed by the Controller.

Working Examples¶

RCTL can be embedded into any kind of workflow automation or CI platform such as Jenkins, CircleCI, GitHub Actions, GitLab etc. Review the CI Integrations Section for additional details and examples on how to embed RCTL into your preferred CI platform.

Important

Working examples of integrations are available on a public Github repository.

Platform Support¶

RCTL is supported on Windows, Mac, and Linux operating systems.

Windows	Linux	macOS
Intel/AMD (x86_64)	Intel/AMD (x86_64), ARM64	Intel/AMD (x86_64), ARM64

Note

On macOS, the Intel/AMD (x86_64) binary can also be used on ARM-based Macs by enabling Rosetta 2.

Download RCTL¶

Manual¶

The Web console provides several conveniences for end users (developers etc) by making it intuitive for them to download the RCTL binaries.

On the left panel of the admin console, click on "My Tools".
Click on the download button that matches your operating system and system architecture to download the package.

Automated¶

Workflow automation systems and pipelines can embed the "download URLs" for RCTL binaries. Note that these download URLs will always provide the latest version of the RCTL CLI.

OS	Architecture	RCTL Download URL
macOS	Intel/AMD (x86_64)	https://rafay-prod-cli.s3-us-west-2.amazonaws.com/publish/rctl-darwin-amd64.tar.bz2
macOS	ARM64 (Apple M1/M2)	https://rafay-prod-cli.s3-us-west-2.amazonaws.com/publish/rctl-darwin-arm64.tar.bz2
Windows	Intel/AMD (x86_64)	https://rafay-prod-cli.s3-us-west-2.amazonaws.com/publish/rctl-windows-amd64.zip
Linux	Intel/AMD (x86_64)	https://rafay-prod-cli.s3-us-west-2.amazonaws.com/publish/rctl-linux-amd64.tar.bz2
Linux	ARM64	https://rafay-prod-cli.s3-us-west-2.amazonaws.com/publish/rctl-linux-arm64.tar.bz2

Version¶

Use the following steps to check the version of RCTL. Users are encouraged to upgrade to the latest versions on a periodic basis (esp. with every release) to ensure they can leverage the latest functionality.

Open Terminal (on macOS or Linux) or Command Prompt (on Windows)
Navigate (i.e. change directory) to the folder where RCTL was unzipped
Type the following command

For amd64

./rctl version
VERSION: r3.6.0
BUILD: r3.6.1-1
BUILD-TIME: Tue 02 Sep 2025 06:04:46 AM UTC
ARCH: darwin/amd64

For arm64

./rctl version
VERSION: r3.6.0
BUILD: r3.6.1-1
BUILD-TIME: Tue 02 Sep 2025 06:04:46 AM UTC
ARCH: darwin/arm64

Embedded Help¶

RCTL can provide contextual help when requested.

./rctl --help

You should see output similar to the example shown below.

A CLI tool to manage resources.

Usage:
  rctl [command]

Available Commands:
  activate                activate pipelines
  apply                   apply for creating or updating resources in Rafay Console
  cancel                  cancel
  cloudevents             get cloudevents for EKS cluster, nodegroup and addons
  completion              Generate completion script
  config                  Manage configuration of the CLI utility
  convert2managed         Convert various resources to managed.
  cordon                  Cordon node in your cluster
  create                  Create various resources in Console
  deactivate              deactivate pipelines
  debug                   debug cluster conditions
  delete                  Delete various resources in Console
  deploy                  deploy various resources in Console
  destroy                 destroy various resources in Console
  download                Download various resources in Console
  drain                   Drain node or nodegroup in your cluster
  execute                 execute
  generate                Generate various resources in Console
  get                     get various resources in Console
  getjobs                 getjobs
  gettargets              gettargets
  help                    Help about any command
  kubeconfig              Generate kubeconfig
  migrate-to-access-entry Migrates existing IAM identities from aws-auth configmap to access entries
  migrate-to-pod-identity Migrates all IRSA to pod identity associations
  publish                 Publish workloads
  scale                   Scale various resources in Console
  schedule                Schedule various resources in Console
  set                     Set various resources in Console
  share                   Share various resources in Console
  start                   start pipelines and clusters in console
  status                  Find out the status of resources like workloads, fleetplans
  stop                    stop pipelines and clusters in console
  terminate               terminate ongoing operations
  uncordon                Uncordon node or nodegroup in your cluster
  undeploy                Undeploy
  unpublish               Unpublish resources like workloads
  update                  update the details of various resource
  upgrade                 Upgrade various resources in Console
  validate                Validate resources like workloads
  version                 Displays version of the CLI utility
  workload                Manage workloads

Flags:
  -c, --config string    Customize cli config file
  -d, --debug            Enable debug logs
  -h, --help             help for rctl
  -o, --output string    Print json, yaml or table output. Default is table (default "table")
  -p, --project string   provide a specific project context
  -v, --verbose          Verbose mode. A lot more information output.
      --wait             Wait for the operation to complete

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

Usage Modes¶

The RCTL CLI can be used in both Interactive and Scripted modes.

Interactive Mode¶

This is the default mode and is primarily meant for human users that wish to view the results in a human-readable format.

Scripted Mode¶

This mode is useful when RCTL is embedded into a workflow such as an automation pipeline. The generated output will ideally be in a JSON or YAML format that can be consumed programmatically by the automation platform.

Exit Codes¶

The RCTL CLI returns an exit code (aka return code) for every command. The standard exit code is "0" for SUCCESS. Any other number for an exit code should be considered an ERROR.

To get the exit code, type "echo $?" at the command prompt after the command completes. Customers can use these exit codes to check for status of a CLI command when it is embedded into a workflow/pipeline.

#!/bin/bash

./rctl version
if [ $? -eq 0 ]
then
  echo "The command ran OK"
  exit 0
else
  echo "The command failed"
  exit 1
fi

Troubleshooting¶

RCTL can be configured to print detailed information via "verbose mode" to assist with troubleshooting. During a support call, support may request you to use the "debug" mode to assist with debugging.

Verbose Mode¶

For example, to enable "verbose" mode while retrieving the list of workloads

./rctl get workload --verbose

Debug Mode¶

For example, to enable "debug" mode while retrieving the list of workloads

./rctl get workload --debug

Auto Completion¶

RCTL can generate auto completion scripts for your target platform and shell.

./rctl completion -h

On Linux or macOS, you can use the following command to identify the current shell. In the example below, the current shell is "bash".

echo $SHELL
/bin/bash