Rancher CLI

Rancher CLI

The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.

Download Rancher CLI

The binary can be downloaded directly from the UI.

In the upper left corner, click ☰.
At the bottom of the navigation sidebar menu, click About.
Under the CLI Downloads section, there are links to download the binaries for Windows, Mac, and Linux. You can also check the releases page for our CLI for direct downloads of the binary.

Requirements

After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:

Your Rancher Server URL, which is used to connect to Rancher Server.
An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see Creating an API Key.

CLI Authentication

Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace <BEARER_TOKEN> and <SERVER_URL> with your information):

$ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>

If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.

Project Selection

Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a project to work on, use the command ./rancher context switch. When you enter this command, a list of available projects displays. Enter a number to choose your project.

Example: ./rancher context switch Output

User:rancher-cli-directory user$ ./rancher context switch
NUMBER    CLUSTER NAME   PROJECT ID              PROJECT NAME
1         cluster-2      c-7q96s:p-h4tmb         project-2
2         cluster-2      c-7q96s:project-j6z6d   Default
3         cluster-1      c-lchzv:p-xbpdt         project-1
4         cluster-1      c-lchzv:project-s2mch   Default
Select a Project:

After you enter a number, the console displays a message that you’ve changed projects.

INFO[0005] Setting new context to project project-1
INFO[0005] Saving config to /Users/markbishop/.ranchcli2.json

Ensure you can run rancher kubectl get pods successfully.

Commands

The following commands are available for use in Rancher CLI.

Command	Result
`apps, [app]`	Performs operations on catalog applications (i.e., individual Helm charts) or Rancher charts.
`catalog`	Performs operations on catalogs.
`clusters, [cluster]`	Performs operations on your clusters.
`context`	Switches between Rancher projects. For an example, see Project Selection.
`globaldns`	Performs operations on global DNS providers and entries.
`inspect [OPTIONS] [RESOURCEID RESOURCENAME]`	Displays details about Kubernetes resources or Rancher resources (i.e.: projects and workloads). Specify resources by name or ID.
`kubectl`	Runs kubectl commands.
`login, [l]`	Logs into a Rancher Server. For an example, see CLI Authentication.
`machines, [machine]`	Performs operations on machines.
`multiclusterapps, [multiclusterapp mcapps mcapp]`	Performs operations with multi-cluster apps.
`namespaces, [namespace]`	Performs operations on namespaces.
`nodes, [node]`	Performs operations on nodes.
`projects, [project]`	Performs operations on projects.
`ps`	Displays workloads in a project.
`server`	Performs operations for the server.
`settings, [setting]`	Shows the current settings for your Rancher Server.
`ssh`	Connects to one of your cluster nodes using the SSH protocol.
`up`	Applies compose config.
`wait`	Waits for resources cluster, app, project, multiClusterApp.
`token`	Authenticates and generates new kubeconfig token.
`help, [h]`	Shows a list of commands or help for one command.

Rancher CLI Help

Once logged into Rancher Server using the CLI, enter ./rancher --help for a list of commands.

All commands accept the --help flag, which documents each command’s usage.

Limitations

The Rancher CLI cannot be used to install dashboard apps or Rancher feature charts.