The OpenShift Container Platform CLI exposes commands for managing your applications, as well as lower level tools to interact with each component of your system. This topic guides you through getting started with the CLI, including installation and logging in to create your first project.

Certain operations require Git to be locally installed on a client. For example, the command to create an application using a remote Git repository:

$ oc new-app https://github.com/<your_user>/<your_git_repo>

Before proceeding, install Git on your workstation. See the official Git documentation for instructions per your workstation’s operating system.

The easiest way to download the CLI is by accessing the About page on the web console if your cluster administrator has enabled the download links:

Installation options for the CLI vary depending on your operating system.

To log in using the CLI, collect your token from the web console’s Command Line page, which is accessed from Command Line Tools in the Help menu. The token is hidden, so you must click the copy to clipboard button at the end of the oc login line on the Command Line Tools page, then paste the copied contents to show the token.

2.3.1. For Windows

The CLI for Windows is provided as a zip archive; you can download it from the Red Hat Customer Portal. After logging in with your Red Hat account, you must have an active OpenShift Enterprise subscription to access the downloads page:

Download the CLI from the Red Hat Customer Portal

Alternatively, if the cluster administrator has enabled it, you can download and unpack the CLI from the About page on the web console.

Tutorial Video:

The following video walks you through this process: Click here to watch

Then, unzip the archive with a ZIP program and move the oc binary to a directory on your PATH. To check your PATH, open the Command Prompt and run:

C:\> path

2.3.2. For Mac OS X

The CLI for Mac OS X is provided as a tar.gz archive; you can download it from the Red Hat Customer Portal. After logging in with your Red Hat account, you must have an active OpenShift Enterprise subscription to access the downloads page:

Download the CLI from the Red Hat Customer Portal

Alternatively, if the cluster administrator has enabled it, you can download and unpack the CLI from the About page on the web console.

Tutorial Video:

The following video walks you through this process: Click here to watch

Then, unpack the archive and move the oc binary to a directory on your PATH. To check your PATH, open a Terminal window and run:

$ echo $PATH

2.3.3. For Linux

For Red Hat Enterprise Linux (RHEL) 7, you can install the CLI as an RPM using Red Hat Subscription Management (RHSM) if you have an active OpenShift Enterprise subscription on your Red Hat account:

# subscription-manager register
# subscription-manager attach --pool=<pool_ID> 1
# subscription-manager repos --enable="rhel-7-server-ose-3.5-rpms"
# yum install atomic-openshift-clients

1

Pool ID for an active OpenShift Enterprise subscription

For RHEL, Fedora, and other Linux distributions, you can also download the CLI directly from the Red Hat Customer Portal as a tar.gz archive. After logging in with your Red Hat account, you must have an active OpenShift Enterprise subscription to access the downloads page.

Download the CLI from the Red Hat Customer Portal

Tutorial Video:

The following video walks you through this process: Click here to watch

Alternatively, if the cluster administrator has enabled it, you can download and unpack the CLI from the About page on the web console.

Then, unpack the archive and move the oc binary to a directory on your PATH. To check your path, run:

$ echo $PATH

To unpack the archive:

$ tar -xf <file>

Note

If you do not use RHEL or Fedora, ensure that libc is installed and on your library path. If libc is not available, you might see the following error when you run CLI commands:

oc: No such file or directory

The oc login command is the best way to initially set up the CLI, and it serves as the entry point for most users. The interactive flow helps you establish a session to an OpenShift Container Platform server with the provided credentials. The information is automatically saved in a CLI configuration file that is then used for subsequent commands.

The following example shows the interactive setup and login using the oc login command:

$ oc login
OpenShift server [https://localhost:8443]: https://openshift.example.com 1

Username: alice 2
Authentication required for https://openshift.example.com (openshift)
Password: ******
Login successful. 3

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

    $ oc new-project <projectname> 4

Welcome to OpenShift! See 'oc help' to get started.

When you have completed the CLI configuration, subsequent commands use the configuration file for the server, session token, and project information.

You can log out of CLI using the oc logout command:

$ oc logout
User, alice, logged out of https://openshift.example.com

If you log in after creating or being granted access to a project, a project you have access to is automatically set as the current default, until switching to another one:

$ oc login
Username: alice
Authentication required for https://openshift.example.com (openshift)
Password:
Login successful.

Using project "aliceproject".

Additional options are also available for the oc login command.

$ oc login -u system:admin -n default

A CLI configuration file permanently stores oc options and contains a series of authentication mechanisms and OpenShift Container Platform server connection information associated with nicknames.

As described in the previous section, the oc login command automatically creates and manages CLI configuration files. All information gathered by the command is stored in a configuration file located in ~/.kube/config. The current CLI configuration can be viewed using the following command:

$ oc config view
apiVersion: v1
clusters:
- cluster:
    server: https://openshift.example.com
  name: openshift
contexts:
- context:
    cluster: openshift
    namespace: aliceproject
    user: alice
  name: alice
current-context: alice
kind: Config
preferences: {}
users:
- name: alice
  user:
    token: NDM2N2MwODgtNjI1Yy10N3VhLTg1YmItYzI4NDEzZDUyYzVi

CLI configuration files can be used to setup multiple CLI profiles using various OpenShift Container Platform servers, namespaces, and users so that you can switch easily between them. The CLI can support multiple configuration files; they are loaded at runtime and merged together along with any override options specified from the command line.

A project in OpenShift Container Platform contains multiple objects to make up a logical application.

Most oc commands run in the context of a project. The oc login selects a default project during initial setup to be used with subsequent commands. Use the following command to display the project currently in use:

$ oc project

If you have access to multiple projects, use the following syntax to switch to a particular project by specifying the project name:

$ oc project <project_name>

For example:

$ oc project project02
Now using project 'project02'.

$ oc project project03
Now using project 'project03'.

$ oc project
Using project 'project03'.

The oc status command shows a high level overview of the project currently in use, with its components and their relationships, as shown in the following example:

$ oc status
In project OpenShift 3 Sample (test)

service database-test (172.30.17.113:6434 -> 3306)
  database-test deploys docker.io/library/mysql:latest
    #1 deployed 47 hours ago

service frontend-test (172.30.17.236:5432 -> 8080)
  frontend-test deploys origin-ruby-sample:test <-
    builds https://github.com/openshift/ruby-hello-world with docker.io/openshift/ruby-20-centos7:latest
    not built yet
    #1 deployment waiting on image

To see more information about a service or deployment config, use 'oc describe service <name>' or 'oc describe dc <name>'.
You can use 'oc get pods,svc,dc,bc,builds' to see lists of each of the types described above.

After you have logged in, you can create a new application and explore some common CLI operations.

A CLI configuration file allows you to configure different profiles, or contexts, for use with the OpenShift CLI. A context consists of user authentication and OpenShift Container Platform server information associated with a nickname.

Contexts allow you to easily switch between multiple users across multiple OpenShift Container Platform servers, or clusters, when using issuing CLI operations. Nicknames make managing CLI configuration easier by providing short-hand references to contexts, user credentials, and cluster details.

After logging in with the CLI for the first time, OpenShift Container Platform creates a ~/.kube/config file if one does not already exist. As more authentication and connection details are provided to the CLI, either automatically during an oc login operation or by setting them explicitly, the updated information is stored in the configuration file:

apiVersion: v1
clusters: 1
- cluster:
    insecure-skip-tls-verify: true
    server: https://openshift1.example.com:8443
  name: openshift1.example.com:8443
- cluster:
    insecure-skip-tls-verify: true
    server: https://openshift2.example.com:8443
  name: openshift2.example.com:8443
contexts: 2
- context:
    cluster: openshift1.example.com:8443
    namespace: alice-project
    user: alice/openshift1.example.com:8443
  name: alice-project/openshift1.example.com:8443/alice
- context:
    cluster: openshift1.example.com:8443
    namespace: joe-project
    user: alice/openshift1.example.com:8443
  name: joe-project/openshift1/alice
current-context: joe-project/openshift1.example.com:8443/alice 3
kind: Config
preferences: {}
users: 4
- name: alice/openshift1.example.com:8443
  user:
    token: xZHd2piv5_9vQrg-SKXRJ2Dsl9SceNJdhNTljEKTb8k

The CLI can support multiple configuration files; they are loaded at runtime and merged together along with any override options specified from the command line.

After you are logged in, you can use the oc status command or the oc project command to verify your current working environment:

$ oc status
oc status
In project Joe's Project (joe-project)

service database (172.30.43.12:5434 -> 3306)
  database deploys docker.io/openshift/mysql-55-centos7:latest
    #1 deployed 25 minutes ago - 1 pod

service frontend (172.30.159.137:5432 -> 8080)
  frontend deploys origin-ruby-sample:latest <-
    builds https://github.com/openshift/ruby-hello-world with joe-project/ruby-20-centos7:latest
    #1 deployed 22 minutes ago - 2 pods

To see more information about a service or deployment, use 'oc describe service <name>' or 'oc describe dc <name>'.
You can use 'oc get all' to see lists of each of the types described above.

$ oc project
Using project "joe-project" from context named "joe-project/openshift1.example.com:8443/alice" on server "https://openshift1.example.com:8443".

To log in using any other combination of user credentials and cluster details, run the oc login command again and supply the relevant information during the interactive process. A context is constructed based on the supplied information if one does not already exist.

If you are already logged in and want to switch to another project the current user already has access to, use the oc project command and supply the name of the project:

$ oc project alice-project
Now using project "alice-project" on server "https://openshift1.example.com:8443".

At any time, you can use the oc config view command to view your current, full CLI configuration, as seen in the above output.

Additional CLI configuration commands are also available for more advanced usage.

$ oc login -u system:admin -n default

If you want to manually configure your CLI configuration files, you can use the oc config command instead of modifying the files themselves. The oc config command includes a number of helpful subcommands for this purpose:

$ oc config set-credentials <user_nickname>
[--client-certificate=<path/to/certfile>] [--client-key=<path/to/keyfile>]
[--token=<bearer_token>] [--username=<basic_user>] [--password=<basic_password>]

$ oc config set-cluster <cluster_nickname> [--server=<master_ip_or_fqdn>]
[--certificate-authority=<path/to/certificate/authority>]
[--api-version=<apiversion>] [--insecure-skip-tls-verify=true]

$ oc config set-context <context_nickname> [--cluster=<cluster_nickname>]
[--user=<user_nickname>] [--namespace=<namespace>]

$ oc config use-context <context_nickname>

$ oc config set <property_name> <property_value>

$ oc config unset <property_name>

$ oc config view

$ oc config view --config=<specific_filename>

Example Usage

Consider the following configuration workflow. First, set credentials for a user nickname alice that uses an access token:

$ oc config set-credentials alice --token=NDM2N2MwODgtNjI1Yy10N3VhLTg1YmItYzI4NDEzZDUyYzVi

Set a cluster entry named openshift1:

$ oc config set-cluster openshift1 --server=https://openshift1.example.com

Set a context named alice that uses the alice user and the openshift1 cluster:

$ oc config set-context alice --cluster=openshift1 --user=alice

Now that the alice context has been created, switch to that context:

$ oc config use-context alice

Set the aliceproject namespace for the alice context:

$ oc config set contexts.alice.namespace aliceproject

You can now view the configuration that has been created:

$ oc config view
apiVersion: v1
clusters:
- cluster:
    server: https://openshift1.example.com
  name: openshift1
contexts:
- context:
    cluster: openshift1
    namespace: aliceproject
    user: alice
  name: alice
current-context: alice 1
kind: Config
preferences: {}
users:
- name: alice
  user:
    token: NDM2N2MwODgtNjI1Yy10N3VhLTg1YmItYzI4NDEzZDUyYzVi

All subsequent CLI operations will use the alice context, unless otherwise specified by overriding CLI options or until the context is switched.

When issuing CLI operations, the loading and merging order for the CLI configuration follows these rules:

This topic provides information on the developer CLI operations and their syntax. You must setup and login with the CLI before you can perform these operations.

The developer CLI uses the oc command, and is used for project-level operations. This differs from the administrator CLI, which uses the oc adm command for more advanced, administrator operations.

The developer CLI allows interaction with the various objects that are managed by OpenShift Container Platform. Many common oc operations are invoked using the following syntax:

$ oc <action> <object_type> <object_name>

This specifies:

For example, the oc get operation returns a complete list of services that are currently defined:

$ oc get svc
NAME              LABELS                                    SELECTOR                  IP              PORT(S)
docker-registry   docker-registry=default                   docker-registry=default   172.30.78.158   5000/TCP
kubernetes        component=apiserver,provider=kubernetes   <none>                    172.30.0.2      443/TCP
kubernetes-ro     component=apiserver,provider=kubernetes   <none>                    172.30.0.1      80/TCP

The oc describe operation can then be used to return detailed information about a specific object:

$ oc describe svc docker-registry
Name:			docker-registry
Labels:			docker-registry=default
Selector:		docker-registry=default
IP:			172.30.78.158
Port:			<unnamed>	5000/TCP
Endpoints:		10.128.0.2:5000
Session Affinity:	None
No events.