Red Hat SummitThis documentation is for a release that is no longer maintained
See documentation for the latest supported version 3 or the latest supported version 4.Chapter 4. Developer CLI commands
4.1. Basic CLI commands
4.1.1. explain
Display documentation for a certain resource.
Example: Display documentation for Pods
oc explain pods
$ oc explain pods4.1.2. login
Log in to the OpenShift Container Platform server and save login information for subsequent use.
Example: Interactive login
oc login
$ oc loginExample: Log in specifying a user name
oc login -u user1
$ oc login -u user14.1.3. new-app
Create a new application by specifying source code, a template, or an image.
Example: Create a new application from a local Git repository
oc new-app .
$ oc new-app .Example: Create a new application from a remote Git repository
oc new-app https://github.com/sclorg/cakephp-ex
$ oc new-app https://github.com/sclorg/cakephp-exExample: Create a new application from a private remote repository
oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret
$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret4.1.4. new-project
Create a new project and switch to it as the default project in your configuration.
Example: Create a new project
oc new-project myproject
$ oc new-project myproject4.1.5. project
Switch to another project and make it the default in your configuration.
Example: Switch to a different project
oc project test-project
$ oc project test-project4.1.6. projects
Display information about the current active project and existing projects on the server.
Example: List all projects
oc projects
$ oc projects4.1.7. status
Show a high-level overview of the current project.
Example: Show the status of the current project
oc status
$ oc status4.2. Build and Deploy CLI commands
4.2.1. cancel-build
Cancel a running, pending, or new build.
Example: Cancel a build
oc cancel-build python-1
$ oc cancel-build python-1Example: Cancel all pending builds from the python BuildConfig
oc cancel-build buildconfig/python --state=pending
$ oc cancel-build buildconfig/python --state=pending4.2.2. import-image
Import the latest tag and image information from an image repository.
Example: Import the latest image information
oc import-image my-ruby
$ oc import-image my-ruby4.2.3. new-build
Create a new BuildConfig from source code.
Example: Create a BuildConfig from a local Git repository
oc new-build .
$ oc new-build .Example: Create a BuildConfig from a remote Git repository
oc new-build https://github.com/sclorg/cakephp-ex
$ oc new-build https://github.com/sclorg/cakephp-ex4.2.4. rollback
Revert an application back to a previous Deployment.
Example: Roll back to the last successful Deployment
oc rollback php
$ oc rollback phpExample: Roll back to a specific version
oc rollback php --to-version=3
$ oc rollback php --to-version=34.2.5. rollout
Start a new rollout, view its status or history, or roll back to a previous revision of your application.
Example: Roll back to the last successful Deployment
oc rollout undo deploymentconfig/php
$ oc rollout undo deploymentconfig/phpExample: Start a new rollout for a DeploymentConfig with its latest state
oc rollout latest deploymentconfig/php
$ oc rollout latest deploymentconfig/php4.2.6. start-build
Start a build from a BuildConfig or copy an existing build.
Example: Start a build from the specified BuildConfig
oc start-build python
$ oc start-build pythonExample: Start a build from a previous build
oc start-build --from-build=python-1
$ oc start-build --from-build=python-1Example: Set an environment variable to use for the current build
oc start-build python --env=mykey=myvalue
$ oc start-build python --env=mykey=myvalue4.2.7. tag
Tag existing images into imagestreams.
Example: Configure the ruby image’s latest tag to refer to the image for the 2.0 tag
oc tag ruby:latest ruby:2.0
$ oc tag ruby:latest ruby:2.04.3. Application management CLI commands
4.3.1. annotate
Update the annotations on one or more resources.
Example: Add an annotation to a Route
oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist="192.168.1.10"
$ oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist="192.168.1.10"Example: Remove the annotation from the Route
oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist-
$ oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist-4.3.2. apply
Apply a configuration to a resource by file name or standard in (stdin) in JSON or YAML format.
Example: Apply the configuration in pod.json to a Pod
oc apply -f pod.json
$ oc apply -f pod.json4.3.3. autoscale
Autoscale a DeploymentConfig or ReplicationController.
Example: Autoscale to a minimum of two and maximum of five Pods
oc autoscale deploymentconfig/parksmap-katacoda --min=2 --max=5
$ oc autoscale deploymentconfig/parksmap-katacoda --min=2 --max=54.3.4. create
Create a resource by file name or standard in (stdin) in JSON or YAML format.
Example: Create a Pod using the content in pod.json
oc create -f pod.json
$ oc create -f pod.json4.3.5. delete
Delete a resource.
Example: Delete a Pod named parksmap-katacoda-1-qfqz4
oc delete pod/parksmap-katacoda-1-qfqz4
$ oc delete pod/parksmap-katacoda-1-qfqz4Example: Delete all Pods with the app=parksmap-katacoda label
oc delete pods -l app=parksmap-katacoda
$ oc delete pods -l app=parksmap-katacoda4.3.6. describe
Return detailed information about a specific object.
Example: Describe a Deployment named example
oc describe deployment/example
$ oc describe deployment/exampleExample: Describe all Pods
oc describe pods
$ oc describe pods4.3.7. edit
Edit a resource.
Example: Edit a DeploymentConfig using the default editor
oc edit deploymentconfig/parksmap-katacoda
$ oc edit deploymentconfig/parksmap-katacodaExample: Edit a DeploymentConfig using a different editor
OC_EDITOR="nano" oc edit deploymentconfig/parksmap-katacoda
$ OC_EDITOR="nano" oc edit deploymentconfig/parksmap-katacodaExample: Edit a DeploymentConfig in JSON format
oc edit deploymentconfig/parksmap-katacoda -o json
$ oc edit deploymentconfig/parksmap-katacoda -o json4.3.8. expose
Expose a Service externally as a Route.
Example: Expose a Service
oc expose service/parksmap-katacoda
$ oc expose service/parksmap-katacodaExample: Expose a Service and specify the host name
oc expose service/parksmap-katacoda --hostname=www.my-host.com
$ oc expose service/parksmap-katacoda --hostname=www.my-host.com4.3.9. get
Display one or more resources.
Example: List Pods in the default namespace
oc get pods -n default
$ oc get pods -n defaultExample: Get details about the python DeploymentConfig in JSON format
oc get deploymentconfig/python -o json
$ oc get deploymentconfig/python -o json4.3.10. label
Update the labels on one or more resources.
Example: Update the python-1-mz2rf Pod with the label status set to unhealthy
oc label pod/python-1-mz2rf status=unhealthy
$ oc label pod/python-1-mz2rf status=unhealthy4.3.11. scale
Set the desired number of replicas for a ReplicationController or a DeploymentConfig.
Example: Scale the ruby-app DeploymentConfig to three Pods
oc scale deploymentconfig/ruby-app --replicas=3
$ oc scale deploymentconfig/ruby-app --replicas=34.3.12. secrets
Manage secrets in your project.
Example: Allow my-pull-secret to be used as an image pull secret by the default service account
oc secrets link default my-pull-secret --for=pull
$ oc secrets link default my-pull-secret --for=pull4.3.13. serviceaccounts
Get a token assigned to a service account or create a new token or kubeconfig file for a service account.
Example: Get the token assigned to the default service account
oc serviceaccounts get-token default
$ oc serviceaccounts get-token default4.3.14. set
Configure existing application resources.
Example: Sets the name of a secret on a BuildConfig
oc set build-secret --source buildconfig/mybc mysecret
$ oc set build-secret --source buildconfig/mybc mysecret4.4. Troubleshooting and debugging CLI commands
4.4.1. attach
Attach the shell to a running container.
Example: Get output from the python container from Pod python-1-mz2rf
oc attach python-1-mz2rf -c python
$ oc attach python-1-mz2rf -c python4.4.2. cp
Copy files and directories to and from containers.
Example: Copy a file from the python-1-mz2rf Pod to the local file system
oc cp default/python-1-mz2rf:/opt/app-root/src/README.md ~/mydirectory/.
$ oc cp default/python-1-mz2rf:/opt/app-root/src/README.md ~/mydirectory/.4.4.3. debug
Launch a command shell to debug a running application.
Example: Debug the python Deployment
oc debug deploymentconfig/python
$ oc debug deploymentconfig/python4.4.4. exec
Execute a command in a container.
Example: Execute the ls command in the python container from Pod python-1-mz2rf
oc exec python-1-mz2rf -c python ls
$ oc exec python-1-mz2rf -c python ls4.4.5. logs
Retrieve the log output for a specific build, BuildConfig, DeploymentConfig, or Pod.
Example: Stream the latest logs from the python DeploymentConfig
oc logs -f deploymentconfig/python
$ oc logs -f deploymentconfig/python4.4.6. port-forward
Forward one or more local ports to a Pod.
Example: Listen on port 8888 locally and forward to port 5000 in the Pod
oc port-forward python-1-mz2rf 8888:5000
$ oc port-forward python-1-mz2rf 8888:50004.4.7. proxy
Run a proxy to the Kubernetes API server.
Example: Run a proxy to the API server on port 8011 serving static content from ./local/www/
oc proxy --port=8011 --www=./local/www/
$ oc proxy --port=8011 --www=./local/www/4.4.8. rsh
Open a remote shell session to a container.
Example: Open a shell session on the first container in the python-1-mz2rf Pod
oc rsh python-1-mz2rf
$ oc rsh python-1-mz2rf4.4.9. rsync
Copy contents of a directory to or from a running Pod container. Only changed files are copied using the rsync command from your operating system.
Example: Synchronize files from a local directory with a Pod directory
oc rsync ~/mydirectory/ python-1-mz2rf:/opt/app-root/src/
$ oc rsync ~/mydirectory/ python-1-mz2rf:/opt/app-root/src/4.4.10. run
Create and run a particular image. By default, this creates a DeploymentConfig to manage the created containers.
Example: Start an instance of the perl image with three replicas
oc run my-test --image=perl --replicas=3
$ oc run my-test --image=perl --replicas=34.4.11. wait
Wait for a specific condition on one or more resources.
Example: Wait for the python-1-mz2rf Pod to be deleted
oc wait --for=delete pod/python-1-mz2rf
$ oc wait --for=delete pod/python-1-mz2rf4.5. Advanced developer CLI commands
4.5.1. api-resources
Display the full list of API resources that the server supports.
Example: List the supported API resources
oc api-resources
$ oc api-resources4.5.2. api-versions
Display the full list of API versions that the server supports.
Example: List the supported API versions
oc api-versions
$ oc api-versions4.5.3. auth
Inspect permissions and reconcile RBAC roles.
Example: Check whether the current user can read Pod logs
oc auth can-i get pods --subresource=log
$ oc auth can-i get pods --subresource=logExample: Reconcile RBAC roles and permissions from a file
oc auth reconcile -f policy.json
$ oc auth reconcile -f policy.json4.5.4. cluster-info
Display the address of the master and cluster services.
Example: Display cluster information
oc cluster-info
$ oc cluster-info4.5.5. convert
Convert a YAML or JSON configuration file to a different API version and print to standard output (stdout).
Example: Convert pod.yaml to the latest version
oc convert -f pod.yaml
$ oc convert -f pod.yaml4.5.6. extract
Extract the contents of a ConfigMap or secret. Each key in the ConfigMap or secret is created as a separate file with the name of the key.
Example: Download the contents of the ruby-1-ca ConfigMap to the current directory
oc extract configmap/ruby-1-ca
$ oc extract configmap/ruby-1-caExample: Print the contents of the ruby-1-ca ConfigMap to stdout
oc extract configmap/ruby-1-ca --to=-
$ oc extract configmap/ruby-1-ca --to=-4.5.7. idle
Idle scalable resources. An idled Service will automatically become unidled when it receives traffic or it can be manually unidled using the oc scale command.
Example: Idle the ruby-app Service
oc idle ruby-app
$ oc idle ruby-app4.5.8. image
Manage images in your OpenShift Container Platform cluster.
Example: Copy an image to another tag
oc image mirror myregistry.com/myimage:latest myregistry.com/myimage:stable
$ oc image mirror myregistry.com/myimage:latest myregistry.com/myimage:stable4.5.9. observe
Observe changes to resources and take action on them.
Example: Observe changes to Services
oc observe services
$ oc observe services4.5.10. patch
Updates one or more fields of an object using strategic merge patch in JSON or YAML format.
Example: Update the spec.unschedulable field for node node1 to true
oc patch node/node1 -p '{"spec":{"unschedulable":true}}'
$ oc patch node/node1 -p '{"spec":{"unschedulable":true}}'
If you must patch a Custom Resource Definition, you must include the --type merge option in the command.
4.5.11. policy
Manage authorization policies.
Example: Add the edit role to user1 for the current project
oc policy add-role-to-user edit user1
$ oc policy add-role-to-user edit user14.5.12. process
Process a template into a list of resources.
Example: Convert template.json to a resource list and pass to oc create
oc process -f template.json | oc create -f -
$ oc process -f template.json | oc create -f -4.5.13. registry
Manage the integrated registry on OpenShift Container Platform.
Example: Display information about the integrated registry
oc registry info
$ oc registry info4.5.14. replace
Modify an existing object based on the contents of the specified configuration file.
Example: Update a Pod using the content in pod.json
oc replace -f pod.json
$ oc replace -f pod.json4.6. Settings CLI commands
4.6.1. completion
Output shell completion code for the specified shell.
Example: Display completion code for Bash
oc completion bash
$ oc completion bash4.6.2. config
Manage the client configuration files.
Example: Display the current configuration
oc config view
$ oc config viewExample: Switch to a different context
oc config use-context test-context
$ oc config use-context test-context4.6.3. logout
Log out of the current session.
Example: End the current session
oc logout
$ oc logout4.6.4. whoami
Display information about the current session.
Example: Display the currently authenticated user
oc whoami
$ oc whoami4.7. Other developer CLI commands
4.7.1. help
Display general help information for the CLI and a list of available commands.
Example: Display available commands
oc help
$ oc helpExample: Display the help for the new-project command
oc help new-project
$ oc help new-project4.7.2. plugin
List the available plug-ins on the user’s PATH.
Example: List available plug-ins
oc plugin list
$ oc plugin list4.7.3. version
Display the oc client and server versions.
Example: Display version information
oc version
$ oc version
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}