The Rancher Command Line Interface (CLI) manages
Rancher servers from a terminal: log in,
switch between servers, clusters and projects, manage clusters, projects,
namespaces and members, and authenticate kubectl against Rancher-managed
clusters.
Important
rancher-cli is the successor to this CLI and is planned to eventually replace it. It is an experimental, AI-native rewrite for both operators and AI coding agents. It adds structured JSON/YAML output, a server-side dry run before every change, machine-readable errors and exit codes, and an agent skill. It's compatible with Rancher 2.14 or later.
If you use this CLI only as the kubectl credential plugin, rancher-cli is a drop-in replacement. Kubeconfigs downloaded from Rancher keep working after you switch binaries. For everything else, the migration guide maps every command in this CLI to its replacement.
This CLI remains fully supported until an official deprecation notice.
Install · Quickstart · Commands · kubectl · Configuration · Versioning · rancher-cli
User documentation: Rancher CLI in the Rancher Manager docs.
Download a binary from the releases page. Each release has archives for:
| OS | Architectures | Archive |
|---|---|---|
| Linux | amd64, arm64, arm, s390x |
rancher-linux-<arch>-<version>.tar.gz (or .tar.xz) |
| macOS | amd64, arm64 |
rancher-darwin-<arch>-<version>.tar.gz (or .tar.xz) |
| Windows | amd64, 386 |
rancher-windows-<arch>-<version>.zip |
sha256sum.txt in each release lists the checksums. The same files are
published to https://releases.rancher.com/cli2/<version>/.
Extract the archive and put rancher on your PATH:
curl -fsSLO https://github.com/rancher/cli/releases/download/v2.15.3/rancher-linux-amd64-v2.15.3.tar.gz
tar xzf rancher-linux-amd64-v2.15.3.tar.gz
sudo install rancher-v2.15.3/rancher /usr/local/bin/rancher
The image is rancher/cli2, tagged with the release version. Mount a config
directory to keep the login between runs:
docker run --rm -it -v "$HOME/.rancher:/home/cli/.rancher" rancher/cli2:v2.15.3 clusters ls
The container runs as UID 1000, which must be able to read and write the mounted directory.
-
In the Rancher UI, create an API key: Account & API Keys → Create API Key. Copy the bearer token.
-
Log in. The CLI lists your projects and asks you to pick one as the current context:
rancher login https://rancher.example.com --token token-abc12:xyz...Options:
--cacert <file>for a server certificate signed by a private CA,--context <cluster-id>:<project-id>to skip the prompt,--name <name>to name the server in the local config. -
Work with the server:
rancher clusters ls rancher context switch rancher clusters kubeconfig <cluster> > ~/.kube/<cluster>.yaml rancher kubectl get pods -A
Run rancher --help for the full list and rancher <command> --help for
subcommands and flags.
| Command | Purpose |
|---|---|
login |
Log in to a Rancher server and save the credentials. |
server |
List, switch and delete saved servers. |
context |
Show or switch the current cluster and project. |
clusters |
List, create, import and delete clusters; get a kubeconfig; manage cluster members. |
projects |
List, create and delete projects; manage project members. |
namespaces |
List, create, delete and move namespaces in the current project. |
nodes, machines |
List and delete nodes; list machines. |
ps |
List workloads in a project. |
inspect |
Print a resource as JSON or YAML. |
settings |
List, get and set Rancher settings. |
wait |
Wait for a cluster or project to become active. |
kubectl |
Run your local kubectl against the cluster in the current context. |
token, auth get-token |
kubectl exec credential plugin (see below). |
completion |
Print a shell completion script for bash, zsh, fish or PowerShell. |
ssh and clusters add-node work only with nodes created through
docker-machine (RKE1). up applies a compose file. These commands are kept for
existing users.
When the Rancher setting kubeconfig-generate-token is false, kubeconfigs
downloaded from Rancher contain no token. Instead, kubectl runs this CLI as an
exec credential plugin
to get one:
- older kubeconfigs call
rancher token --server <url> --user <name> - newer kubeconfigs call
rancher auth get-token --server <url> --user-id <id> [--auth-provider <name>]
The CLI must be on PATH for kubectl to find it. On first use it asks you
to log in through the auth provider and caches the token in the config file.
Later calls reuse the token until it expires.
--auth-providertakes the name of an auth config, such asgithub,localor one of several OIDC or SAML configs. A provider name such asgenericoidcalso works. If it matches several configs, the CLI asks which one to use.- For OAuth providers,
--auth-flow devicecode(default) prints a URL and a code to enter in a browser.--auth-flow authcodeopens a browser and receives the result on a local port. --cacerts <file>and--skip-verifycontrol TLS verification of the server.rancher token delete <name>|allremoves cached tokens.
rancher login writes the servers, the current context, and API and cached
kubectl tokens to ~/.rancher/cli2.json. Change the directory with
--config <dir> or RANCHER_CONFIG_DIR.
Warning
The file holds API tokens in plaintext. The CLI creates it with mode 0600
in a 0700 directory. Don't copy it to shared locations, and delete servers
you no longer use with rancher server delete.
Two per-server settings have no flag and are set by editing the file:
| Field | Description |
|---|---|
proxyUrl |
HTTP(S) proxy for requests to that server. |
httpTimeoutSeconds |
Request timeout. Default is 60 seconds. |
--debug turns on debug logging.
Rancher CLI is released in lockstep with Rancher: CLI v2.X.Y ships alongside
Rancher v2.X.Y, and the v2.X branch follows Rancher v2.X. main follows
the next Rancher minor. Release candidates are tagged the same way
(v2.16.0-rc.4).
Use the same minor version as your Rancher server where you can. Common commands also work across versions, because the CLI and the server are often upgraded at different times.
- Both binaries are named
rancher. The first one onPATHwins; the rancher-cli installer uses~/.local/bin. Rename one of them to keep both. - rancher-cli doesn't read or import
cli2.json. Log in again withrancher auth login. - Kubeconfigs that call
rancher tokenorrancher auth get-tokenkeep working after you switch binaries. - rancher-cli doesn't support
ssh,up,clusters add-nodeorclusters export. Keep this CLI if you need them.
Requires Go (version in go.mod) and Docker for the image. Each file
in scripts/ is a make target:
make # build, test, validate, package (the CI run)
make build # ./bin/rancher for this machine
CROSS=1 make build # also every release platform, into ./build/bin
make test # go test with the race detector
make lint # golangci-lint
make validate # go mod tidy and verify; fails if the tree changes
make package # archives of ./build/bin into ./dist, and a local rancher/cli image
REPO=<name> make package tags the image <name>/cli instead. Releases are
built by the release workflow from v* tags.
For bugs, questions, comments, corrections and suggestions, open an issue in
rancher/rancher with a title
starting with [cli] , or
click here.
Report security issues as described in the Rancher security policy.
Copyright (c) 2014-2026 Rancher Labs, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.