anchor.diff:  toc::[]
   
   == Overview
  -The OpenShift CLI enables you to create and manage OpenShift projects from a terminal. This is useful for situations where:
  +With the OpenShift command line interface (CLI), you can create and manage OpenShift projects from a terminal. The CLI is ideal in situations where you are:
   
  -* You are working directly with project source code
  -* You are scripting OpenShift operations
  -* You are bandwidth-constrained and can't use the web console
  +* Working directly with project source code
  +* Scripting OpenShift operations
  +* Restricted by bandwidth resources and cannot use the web console
   
  -The CLI commands are available directly from the OpenShift binary by running `openshift cli <command>`, but if `osc` is available on your system, you can treat it as a shortcut to the same commands available through `openshift cli` (`osc <command>`).
  +The CLI commands are available directly from the OpenShift binary with the following syntax:
   
  -NOTE: Throughout this document we will reference `osc`, but you can run the same commands with `openshift cli`.
  +----
  +openshift cli <command>
  +----
  +
  +However, if `osc` is available on your workstation you can use it as a shortcut in place of `openshift cli` in the command syntax:
  +
  +----
  +osc <command>
  +----
  +
  +NOTE: Although `osc` is used in the command examples presented throughout this document, you can substitute `openshift cli` in the command syntax if `osc` is not available on your workstation. 
   
   == Configuring the CLI
  -Running `osc --help` reveals a large number of configuration options. These are well-documented, but some of the main ones you may need are:
  +There are many configuration options available for the OpenShift CLI, and you can access these with the `osc --help` command. The following table describes some of the more common options.
   
  -*-s, --server* +
  -This enables you to specify the hostname of the OpenShift server. You will need to provide this if the server is running on a different host from the CLI.
  +.Common CLI Configuration Options
  +[cols="4,8",options="header"]
  +|===
   
  -*--insecure-skip-tls-verify=true* +
  -This is the quick and dirty way to interact with a server that is using HTTPS. Note, however, that it is not secure.
  +|Option |Description
   
  -*--auth-path* +
  -*--certificate-authority* +
  -*--client-certificate* +
  -*--client-key* +
  -These settings are the _proper_ way to authenticate an OpenShift server that uses HTTPS. Connections set up this way will be secure.
  +.^|`-s, --server`
  +|This option allows you to specify the host name of the OpenShift server. You will need to provide this if the server is running on a different host from the CLI.
  +
  +.^|`--insecure-skip-tls-verify=true`
  +|This option allows quick interaction with an HTTPS server; however, note that it is not secure.
  +
  +a|`--auth-path`
  +
  +`--certificate-authority`
  +
  +`--client-certificate`
  +
  +`--client-key`
  +.^|These settings are used to correctly and securely authenticate with an OpenShift server that uses HTTPS. 
  +|===
   
   [TIP]
   ====
  -*Can I just set these in a configuration file?* +
  -The ability to permanently set `osc` configuration details in a config file is forthcoming. For now you will need to pass these on the command line, or create a shell alias that sets the values that you need.
  +*Can I use a configuration file?* +
  +The ability to permanently configure `osc` options with a configuration file is planned for a future release and is not available at this time. The current workaround is to use the CLI, or you can create a shell alias to configure the required parameters.  
   ====
   
  -== Object Types in the CLI
  -The supported OpenShift object types are:
  +== CLI Object Types 
  +OpenShift supports the following object types, some of which have abbreviated syntax that you can use with `osc`.
   
  -* build
  -* buildConfig
  -* event
  -* minion
  -* pod
  -* replicationController
  -* service
  +.Supported Object Types
  +[options="header"]
  +|===
   
  -Some of these objects also have shorthand equivalent codes for use with `osc`:
  +|Object Type |Abbreviated Version
   
  -* `po` - pods
  -* `rc` - replication controllers
  -* `se` - services
  -* `mi` - minions
  -* `ev` - events
  +|build |
  +|buildconfig |
  +|event |`ev`
  +|minion |`mi`
  +|pod |`po`
  +|replicationController |`rc`
  +|service |`se`
  +|===
   
  -== Common Operations
  -At its heart, the `osc` utility is just a mechanism for interacting with the various objects that OpenShift manages. The common `osc` commands are invoked by specifying an _action_, the _object type_ to perform the action on, and optionally a specific _object name or ID_ of the indicated object type.
  +== Common CLI Operations
  +The CLI allows interaction with the various objects that are managed by OpenShift. The common `osc` operations are invoked by specifying the following:
   
  -For instance, running `osc get se` returns the complete list of currently defined services:
  +* An _action_
  +* The _object type_ to perform the action on
  +* The _object name_ or _ID_ of the specified _object type_
  +
  +In the following example the `osc get` operation returns a complete list of services that are currently defined.
   
   ----
   $ osc get se
  
positive.code: docker-registry     <none>                                    name=registrypod    172.30.17.158       5001
  ----
  
  And running `osc get se kubernetes-ro` returns the same list filtered down to an individual object:
  
  ----
  $ osc get se kubernetes-ro
  
negative.code: kubernetes-ro       component=apiserver,provider=kubernetes   <none>              172.30.17.77        80
  ----
  
  The following table describes the common `osc` operations and provides the general syntax for them.
  
  .Common CLI Operations
  [cols=".^2,.^5,8",options="header"]
  |===
  
  |Operation |Syntax |Description
  
  |`get`
  |`osc get _<object_type>_ _<object_id>_`
  |This command returns a list of objects of the indicated link:#object-types[object type]. If the optional _object name_ or _ID_ is included in the request, the list of results will be filtered by that value.
  
  |`describe`
  |`osc describe _<object_type>_ _<object_id>_`
  |This command returns information about the specific object returned by the query; a specific _object name_ or _ID_ must be provided. The actual information that is available varies as described in link:#object-types[object type].
  
  |`create`
  |`osc create -f _<file_path>_`
  |This command is used to parse a configuration file and create one or more OpenShift objects based on the file contents.
  
  |`create all`
  |`osc createall -d _<dir_path>_ -f _<file_path>_`
  |This command performs the same action as the `create` command. In addition, you can specify a directory with the `-d` option that contains multiple configuration files, a file with the `-f` option that contains multiple configurations, or you can pass configurations through STDIN
  
  |`update`
  |`osc update -f _<file_path>_`
  |This command attempts to modify an existing object based on the contents of the specified configuration file. If the object does not already exist, this command performs the same function as link:#create-create-all[`osc create`].
  
  |`delete`
  a|`osc delete -f _<file_path>_`
  
  `osc delete _<object_type>_ _<object_id>_`
  
  `osc delete _<object_type>_ -l _<label>_`
  .^|This command deletes the specified OpenShift object. An object configuration can also be passed in through STDIN.
  
  |`log`
  |`osc log -f _<pod_name>_ _<container_name>_`
  |This command retrieves the log output for a specific pod or container. This command does not work for other object types.
  |===
  
  == Project CLI Operations
  These advanced operations are used to define and instantiate OpenShift objects at the project level.
  
  .Project CLI Operations
  [cols=".^2,.^5,8",options="header"]
  |===
  
  |Operation |Syntax |Description
  
  |`process`
  |`osc process -f _<template_file_path>_`
  |This command transforms a project template into a project configuration file.
  
  |`apply`
  |`osc apply -f _<config_file_path>_`
  |This command creates all of the OpenShift objects for a given project based on the specified configuration file.
  |===
  
  == Build CLI Operations
  One of the fundamental capabilities of OpenShift is the ability to build applications into a container from source. The following table describes the CLI operations for working with application builds.
  
  .Build CLI Operations
  [cols=".^2,.^5,8",options="header"]
  |===
  
  |Operation |Syntax |Description
  
  |`start-build`
  |`osc start-build _<buildConfig_name>_`
  |This command is used to manually start the build process with the specified build configuration file.
  
  |`start-build`
  |`osc start-build --from-build=_<build_name>_`
  |This command is used to manually start the build process by specifying the name of a previous build as a starting point.
  
  |`cancel-build`
  |`osc cancel-build _<build_name>_`
  |This command stops a build that is in progress.
  
  |`build-logs`
  |`osc cancel-build _<build_name>_`
  |This command retrieves the build logs for the specified build.
  |===
  
  