Getting started with the OpenShift CLI - OpenShift CLI (oc) | CLI tools

About the OpenShift CLI
Installing the OpenShift CLI
Logging in to the OpenShift CLI
Logging in to the OpenShift CLI using a web browser
Using the OpenShift CLI
Getting help
Logging out of the OpenShift CLI

Install and configure the OpenShift CLI (oc) to manage OKD clusters and deploy applications directly from a terminal.

About the OpenShift CLI

With the OpenShift CLI (oc), you can create applications and manage OKD projects from a terminal.

The OpenShift CLI is ideal in the following situations:

Working directly with project source code.
Scripting OKD operations
Managing projects while restricted by bandwidth resources and the web console is unavailable.

Installing the OpenShift CLI

To interact with a OKD cluster from the terminal, install the OpenShift CLI (oc). Depending on your operating system, you can install oc by downloading the binary from the Customer Portal or OKD web console, or by using Homebrew.

Installing the OpenShift CLI by downloading the binary from the Customer Portal

You can download the OpenShift CLI (oc) from the Customer Portal and install it to interact with OKD clusters from a terminal on Linux, Windows, or macOS.

Installing the OpenShift CLI on Linux

To manage your cluster and deploy applications from the command line on Linux, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OKD.

Download and install the new version of oc.

Procedure

Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.
Download oc.tar.gz.
Unpack the archive:
```
$ tar xvf <file>
```
Place the oc binary in a directory that is on your PATH.

To check your PATH, execute the following command:
```
$ echo $PATH
```

Verification

After you install the OpenShift CLI, it is available using the oc command:
```
$ oc <command>
```

Installing the OpenShift CLI on Windows

To manage your cluster and deploy applications from the command line on Windows, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OKD.

Download and install the new version of oc.

Procedure

Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.
Download oc.zip.
Extract the archive with a ZIP program.
Move the oc binary to a directory that is on your PATH variable.

To check your PATH variable, open the command prompt and execute the following command:
```
C:\> path
```

Verification

After you install the OpenShift CLI, it is available using the oc command:
```
C:\> oc <command>
```

Installing the OpenShift CLI on macOS

To manage your cluster and deploy applications from the command line on macOS, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the Red Customer Portal.

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OKD.

Download and install the new version of oc.

Procedure

Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture.
Download oc.tar.gz.
Unpack and unzip the archive.
Move the oc binary to a directory on your PATH variable.

To check your PATH variable, open a terminal and execute the following command:
```
$ echo $PATH
```

Verification

Verify your installation by using an oc command:
```
$ oc <command>
```

Installing the OpenShift CLI by downloading the binary from the web console

You can download the OpenShift CLI (oc) from the web OKD console and install it to interact with OKD clusters from a terminal on Linux, Windows, or macOS.

If you installed an earlier version of oc, you cannot use it to complete all of the commands in OKD 4.22. Download and install the new version of oc.

Installing the OpenShift CLI on Linux using the web console

To manage your cluster and deploy applications from the command line on Linux, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the web console.

Procedure

From the web console, click ?.
Click Command Line Tools.
Select appropriate oc binary for your Linux platform, and then click Download oc for Linux.
Save the file.
Unpack the archive.
```
$ tar xvf <file>
```
Move the oc binary to a directory that is on your PATH.

To check your PATH, execute the following command:
```
$ echo $PATH
```

Verification

After you install the OpenShift CLI, you can use the oc command:
```
$ oc <command>
```

Installing the OpenShift CLI on Windows using the web console

To manage your cluster and deploy applications from the command line on Windows, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the web console.

Procedure

From the web console, click ?.
Click Command Line Tools.
Select the oc binary for Windows platform, and then click Download oc for Windows for x86_64.
Save the file.
Unzip the archive with a ZIP program.
Move the oc binary to a directory that is on your PATH.

To check your PATH, open the command prompt and execute the following command:
```
C:\> path
```

Verification

After you install the OpenShift CLI, you can use the oc command:
```
C:\> oc <command>
```

Installing the OpenShift CLI on macOS using the web console

To manage your cluster and deploy applications from the command line on macOS, install the OpenShift CLI (oc) binary. You can download the OpenShift CLI (oc) from the web console.

Procedure

From the web console, click ?.
Click Command Line Tools.
Select the oc binary for macOS platform, and then click Download oc for Mac for x86_64.

For macOS arm64, click Download oc for Mac for ARM 64.
Save the file.
Unpack and unzip the archive.
Move the oc binary to a directory on your PATH.

To check your PATH, open a terminal and execute the following command:
```
$ echo $PATH
```

Verification

After you install the OpenShift CLI, you can use the oc command:
```
$ oc <command>
```

Installing the OpenShift CLI by using Homebrew

For macOS, you can install the OpenShift CLI (oc) by using the Homebrew package manager.

Prerequisites

You must have Homebrew (brew) installed.

Procedure

Install the openshift-cli package by running the following command:
```
$ brew install openshift-cli
```

Verification

Verify your installation by using an oc command:
```
$ oc <command>
```

Logging in to the OpenShift CLI

You can log in to the OpenShift CLI (oc) to access and manage your cluster.

To access a cluster that is accessible only over an HTTP proxy server, you can set the HTTP_PROXY, HTTPS_PROXY and NO_PROXY variables. These environment variables are respected by the oc CLI so that all communication with the cluster goes through the HTTP proxy.

Authentication headers are sent only when using HTTPS transport.

Prerequisites

You must have access to a OKD cluster.
The OpenShift CLI (oc) is installed.

Procedure

Enter the oc login command and pass in a user name:
```
$ oc login -u user1
```

When prompted, enter the required information:

Example output

Server [https://localhost:8443]: https://openshift.example.com:6443
The server uses a certificate signed by an unknown authority.
You can bypass the certificate check, but any data you send to the server could be intercepted by others.
Use insecure connections? (y/n): y

Authentication required for https://openshift.example.com:6443 (openshift)
Username: user1
Password:
Login successful.

You don't have any projects. You can try to create a new project, by running

    oc new-project <projectname>

Welcome! See 'oc help' to get started.

For the Server prompt, enter the OKD server URL.
For the Use insecure connections? prompt, enter whether to use insecure connections.
For the Username prompt, enter the username to log in with.
For the Password prompt, enter the user’s password.

If you are logged in to the web console, you can generate an oc login command that includes your token and server information. You can use the command to log in to the OpenShift CLI (oc) without the interactive prompts. To generate the command, select Copy login command from the username drop-down menu at the top right of the web console.

You can now create a project or issue other commands for managing your cluster.

Logging in to the OpenShift CLI using a web browser

You can log in to the OpenShift CLI (oc) with the help of a web browser to access and manage your cluster. This allows you to avoid inserting your access token into the command line.

Logging in to the CLI through the web browser runs a server on localhost with HTTP, not HTTPS; use with caution on multi-user workstations.

Prerequisites

You must have access to an OKD cluster.
You must have installed the OpenShift CLI (oc).
You must have a browser installed.

Procedure

Enter the oc login command with the --web flag:
```
$ oc login <cluster_url> --web
```
Optionally, you can specify the server URL and callback port. For example, oc login <cluster_url> --web --callback-port 8280 localhost:8443.
The web browser opens automatically. If it does not, click the link in the command output. If you do not specify the OKD server oc tries to open the web console of the cluster specified in the current oc configuration file. If no oc configuration exists, oc prompts interactively for the server URL.
Example output
```
Opening login URL in the default browser: https://openshift.example.com
Opening in existing browser session.
```
If more than one identity provider is available, select your choice from the options provided.
Enter your username and password into the corresponding browser fields. After you are logged in, the browser displays the text access token received successfully; please return to your terminal.
Check the CLI for a login confirmation.
Example output
```
Login successful.

You don't have any projects. You can try to create a new project, by running

    oc new-project <projectname>
```
The web console defaults to the profile used in the previous session. To switch between Administrator and Developer profiles, log out of the OKD web console and clear the cache.

You can now create a project or issue other commands for managing your cluster.

Using the OpenShift CLI

Review how to complete common tasks with the OpenShift CLI (oc).

Creating a project

Use the oc new-project command to create a new project.

Procedure

Create a new project by running the following command:

$ oc new-project my-project

Example output

Now using project "my-project" on server "https://openshift.example.com:6443".

Creating a new application

Use the oc new-app command to create a new application.

Procedure

Create a new application by running the following command:

$ oc new-app https://github.com/sclorg/cakephp-ex

Example output

--> Found image 40de956 (9 days old) in imagestream "openshift/php" under tag "7.2" for "php"

...

    Run 'oc status' to view your app.

Viewing pods

Use the oc get pods command to view the pods for the current project.

When you run oc inside a pod and do not specify a namespace, the namespace of the pod is used by default.

Procedure

View pods for the current project by running the following command:

$ oc get pods -o wide

Example output

NAME                  READY   STATUS      RESTARTS   AGE     IP            NODE                           NOMINATED NODE
cakephp-ex-1-build    0/1     Completed   0          5m45s   10.131.0.10   ip-10-0-141-74.ec2.internal    <none>
cakephp-ex-1-deploy   0/1     Completed   0          3m44s   10.129.2.9    ip-10-0-147-65.ec2.internal    <none>
cakephp-ex-1-ktz97    1/1     Running     0          3m33s   10.128.2.11   ip-10-0-168-105.ec2.internal   <none>

Viewing pod logs

Use the oc logs command to view logs for a particular pod.

Procedure

View logs for a pod by running the following command:

$ oc logs cakephp-ex-1-deploy

Example output

--> Scaling cakephp-ex-1 to 1
--> Success

Viewing the current project

Use the oc project command to view the current project.

Procedure

View the current project by running the following command:

$ oc project

Example output

Using project "my-project" on server "https://openshift.example.com:6443".

Viewing the status of the current project

Use the oc status command to view information about the current project, such as services, deployments, and build configs.

Procedure

View the status of the current project by running the following command:

$ oc status

Example output

In project my-project on server https://openshift.example.com:6443

svc/cakephp-ex - 172.30.236.80 ports 8080, 8443
  dc/cakephp-ex deploys istag/cakephp-ex:latest <-
    bc/cakephp-ex source builds https://github.com/sclorg/cakephp-ex on openshift/php:7.2
    deployment #1 deployed 2 minutes ago - 1 pod

3 infos identified, use 'oc status --suggest' to see details.

Listing supported API resources

Use the oc api-resources command to view the list of supported API resources on the server.

Procedure

View the supported API resources by running the following command:

$ oc api-resources

Example output

NAME                                  SHORTNAMES       APIGROUP                              NAMESPACED   KIND
bindings                                                                                     true         Binding
componentstatuses                     cs                                                     false        ComponentStatus
configmaps                            cm                                                     true         ConfigMap
...

Getting help

Review the ways to get help with CLI commands and OKD resources.

Procedure

Use oc help to get a list and description of all available CLI commands:

Example: Get general help for the CLI

$ oc help

Example output

OpenShift Client

This client helps you develop, build, deploy, and run your applications on any OpenShift or Kubernetes compatible
platform. It also includes the administrative commands for managing a cluster under the 'adm' subcommand.

Usage:
  oc [flags]

Basic Commands:
  login           Log in to a server
  new-project     Request a new project
  new-app         Create a new application

...

Use the --help flag to get help about a specific CLI command:

Example: Get help for the oc create command

$ oc create --help

Example output

Create a resource by filename or stdin

JSON and YAML formats are accepted.

Usage:
  oc create -f FILENAME [flags]

...

Use the oc explain command to view the description and fields for a particular resource:

Example: View documentation for the Pod resource

$ oc explain pods

Example output

KIND:     Pod
VERSION:  v1

DESCRIPTION:
     Pod is a collection of containers that can run on a host. This resource is
     created by clients and scheduled onto hosts.

FIELDS:
   apiVersion	<string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#resources

...

Logging out of the OpenShift CLI

You can log out the OpenShift CLI (oc) to end your current session.

Procedure

Use the oc logout command.
```
$ oc logout
```
Example output
```
Logged "user1" out on "https://openshift.example.com"
```
This deletes the saved authentication token from the server and removes it from your configuration file.