Rancher CLI

Rancher CLI cheatsheet — manage clusters, workloads, namespaces, contexts. rancher login, rancher clusters ls, rancher kubectl, rancher context switch. Full reference.

6 min read

What it is

The Rancher CLI is a command-line interface for managing your Rancher Kubernetes clusters, workloads, and configurations. You reach for it when you need to automate Rancher operations, script cluster tasks, or manage resources programmatically.

Installation

Linux / macOS

Download the latest release from the Rancher CLI releases page and place the binary in your PATH.

# Example for Linux AMD64
curl -LO https://github.com/rancher/cli/releases/download/v2.7.9/rancher-linux-amd64-v2.7.9.tar.gz
tar -zxvf rancher-linux-amd64-v2.7.9.tar.gz
sudo mv rancher-v2.7.9/rancher /usr/local/bin/rancher
rm -rf rancher-v2.7.9 rancher-linux-amd64-v2.7.9.tar.gz

Windows

Download the latest release from the Rancher CLI releases page and add the directory containing the rancher.exe file to your system’s PATH environment variable.

Core Concepts

  • Rancher Server URL: The base URL of your Rancher instance (e.g., https://rancher.example.com).
  • Access Key / Secret Key: Credentials used to authenticate with the Rancher API. These are typically generated within the Rancher UI under your user settings.
  • Project: A logical grouping of Kubernetes namespaces and resources within a cluster.
  • Cluster: A managed Kubernetes cluster (e.g., RKE, K3s, or imported clusters).
  • Catalog: A collection of Helm charts available for deployment in Rancher.

Commands / Usage

Connecting to Rancher

  • Login to a Rancher server:

    rancher login https://rancher.example.com --token <YOUR_RANCHER_TOKEN>

    Connects to your Rancher server using a bearer token.

  • Login with access and secret keys:

    rancher login https://rancher.example.com --access-key <YOUR_ACCESS_KEY> --secret-key <YOUR_SECRET_KEY>

    Connects to your Rancher server using API access and secret keys.

  • List configured Rancher servers:

    rancher servers

    Displays a list of Rancher servers you have logged into.

  • Use a specific logged-in server:

    rancher context switch <SERVER_NAME_OR_URL>

    Switches the CLI context to a previously logged-in Rancher server.

Managing Clusters

  • List all clusters:

    rancher cluster ls

    Shows all Kubernetes clusters managed by the current Rancher server.

  • Get details of a specific cluster:

    rancher cluster ps --cluster <CLUSTER_NAME_OR_ID>

    Displays information about the nodes in a specific cluster.

  • View cluster status:

    rancher cluster ps --cluster cluster-name

    Shows the status of nodes within the specified cluster.

Managing Projects and Namespaces

  • List projects in the current cluster:

    rancher project ls

    Lists all projects available in the currently selected cluster context.

  • Create a new project:

    rancher project create "My New Project" --cluster <CLUSTER_NAME_OR_ID>

    Creates a new project named "My New Project" in the specified cluster.

  • Switch to a specific project:

    rancher project switch "My New Project"

    Sets the CLI context to the specified project.

  • List namespaces in the current project:

    rancher namespace ls

    Lists all namespaces within the currently selected project.

  • Create a new namespace:

    rancher namespace create "my-app-ns" --cluster <CLUSTER_NAME_OR_ID> --project "My New Project"

    Creates a new namespace named "my-app-ns" within a specific project and cluster.

Managing Workloads (Deployments, StatefulSets, etc.)

  • List workloads in the current namespace:

    rancher workloads ls

    Shows all workloads (Deployments, StatefulSets, DaemonSets, etc.) in the current namespace.

  • Create a workload from a YAML file:

    rancher workloads create --file deployment.yaml

    Deploys resources defined in the deployment.yaml file.

  • Scale a deployment:

    rancher workloads scale deployment-name --replicas 5

    Scales the deployment named deployment-name to 5 replicas.

  • Delete a workload:

    rancher workloads rm deployment-name

    Removes the workload named deployment-name.

Managing Catalogs and Applications

  • List available catalogs:

    rancher catalog ls

    Displays all catalogs configured in Rancher.

  • List applications (Helm charts) in a catalog:

    rancher catalog apps --catalog <CATALOG_NAME>

    Lists available applications within the specified catalog.

  • Install an application:

    rancher catalog install <APP_NAME> --catalog <CATALOG_NAME> --namespace <NAMESPACE> --values values.yaml

    Installs the application <APP_NAME> from <CATALOG_NAME> into the <NAMESPACE> using configurations from values.yaml.

  • Upgrade an installed application:

    rancher catalog upgrade <APP_NAME> --catalog <CATALOG_NAME> --namespace <NAMESPACE> --version <NEW_VERSION> --values values.yaml

    Upgrades an already installed application to a new version.

Managing Kubernetes Resources

  • List all Kubernetes resources of a type:

    rancher kubectl get pods -n default

    Executes a kubectl get pods command against the currently configured cluster and namespace. The Rancher CLI proxies kubectl commands.

  • Apply a Kubernetes manifest:

    rancher kubectl apply -f deployment.yaml

    Applies a Kubernetes manifest file using kubectl via the Rancher CLI.

Other Useful Commands

  • Get Rancher CLI version:

    rancher version

    Displays the currently installed Rancher CLI version.

  • Get help for a command:

    rancher --help
rancher cluster --help
rancher workloads --help

    Provides detailed help information for any command or subcommand.

Common Patterns

  • Deploying an application from a Git repository:

    # Ensure you have cloned the repo and have a deployment.yaml
rancher workloads create --file my-app/deployment.yaml

    This is a fundamental pattern for deploying your applications defined in Kubernetes manifests.

  • Setting up a new application namespace and deploying to it:

    # First, create the project if it doesn't exist
rancher project create "App Projects" --cluster my-cluster

# Then create the namespace within that project
rancher namespace create "frontend-ns" --cluster my-cluster --project "App Projects"

# Now deploy your application to the new namespace
rancher workloads create --file frontend-deployment.yaml --namespace frontend-ns

    A common workflow for organizing applications.

  • Installing a Helm chart with custom values:

    rancher catalog install prometheus \
  --catalog rancher-charts \
  --namespace monitoring \
  --version 11.0.0 \
  --values prometheus-values.yaml

    Installs a specific version of an application using a custom configuration file.

  • Checking the status of a deployment and its pods:

    rancher kubectl rollout status deployment/my-app-deployment -n my-app-ns
rancher kubectl get pods -n my-app-ns -l app=my-app

    Combines rollout status checking with pod listing for troubleshooting.

Gotchas

  • Context Switching: The Rancher CLI relies heavily on context. Always ensure you are operating within the correct Rancher server, cluster, project, and namespace. Use rancher context ls and rancher context switch if unsure.
  • API Token Expiration: Bearer tokens used for rancher login have an expiration. For long-running scripts, using access/secret keys or re-authenticating periodically is necessary.
  • kubectl Proxying: While rancher kubectl works for most commands, be aware that it’s a proxy. Some advanced kubectl features or plugins might not behave as expected or require specific configuration.
  • Resource Naming: Ensure that resource names (clusters, projects, namespaces, workloads) are unique within their scope to avoid conflicts.
  • Permissions: The access/secret keys or token you use must have the necessary permissions within Rancher to perform the actions you’re attempting. Insufficient permissions will result in errors.