// Module included in the following assemblies:
//
// * cli_reference/openshift_cli/extending-cli-plugins.adoc

[id="cli-writing-plugins_{context}"]
= Writing CLI plug-ins

You can write a plug-in for the {product-title} CLI in any programming language
or script that allows you to write command-line commands. Note that you can not
use a plug-in to overwrite an existing `oc` command.

[IMPORTANT]
====
OpenShift CLI plug-ins are currently a Technology Preview feature.
ifdef::openshift-enterprise,openshift-webscale[]
Technology Preview features are not supported with Red Hat production service
level agreements (SLAs), might not be functionally complete, and Red Hat does
not recommend to use them for production. These features provide early access to
upcoming product features, enabling customers to test functionality and provide
feedback during the development process.

See the link:https://access.redhat.com/support/offerings/techpreview/[Red Hat
Technology Preview features support scope] for more information.
endif::[]
====

.Procedure

This procedure creates a simple Bash plug-in that prints a message to the
terminal when the `oc foo` command is issued.

. Create a file called `oc-foo`.
+
When naming your plug-in file, keep the following in mind:

* The file must begin with `oc-` or `kubectl-` in order to be recognized as a
plug-in.
* The file name determines the command that invokes the plug-in. For example, a
plug-in with the file name `oc-foo-bar` can be invoked by a command of
`oc foo bar`. You can also use underscores if you want the command to contain
dashes. For example, a plug-in with the file name `oc-foo_bar` can be invoked
by a command of `oc foo-bar`.

. Add the following contents to the file.
+
[source,bash]
----
#!/bin/bash

# optional argument handling
if [[ "$1" == "version" ]]
then
    echo "1.0.0"
    exit 0
fi

# optional argument handling
if [[ "$1" == "config" ]]
then
    echo $KUBECONFIG
    exit 0
fi

echo "I am a plugin named kubectl-foo"
----

After you install this plug-in for the {product-title} CLI, it can be invoked
using the `oc foo` command.

.Additional resources

* Review the link:https://github.com/kubernetes/sample-cli-plugin[Sample plug-in repository]
for an example of a plug-in written in Go.
* Review the link:https://github.com/kubernetes/cli-runtime/[CLI runtime repository] for a set of utilities to assist in writing plug-ins in Go.