<p>Oftentimes, there are small scripts or commands that people will use in multiple jobs that are not complex enough to warrant creating a <a href="https://docs.screwdriver.cd/user-guide/templates">Screwdriver template</a>. Options such as Git repositories, yum packages, or node modules exist, but there was no clear way to share binaries or scripts across multiple jobs. Recently, we have released Screwdriver Commands (also known as <code>sd-cmd</code>) which solves this problem, allowing users to easily share binary commands or scripts across multiple containers and jobs.</p> <h2>Using a command</h2> <p>The following is an example of using an sd-cmd. You can configure any commands or scripts in <code>screwdriver.yaml</code> like this:</p> <p>Example:</p> <pre><code>jobs: main: requires: [~pr, ~commit] steps: - exec: sd-cmd exec foo/bar@1 -baz sample </code></pre> <!-- more --><p>Format for using sd-cmd:</p> <pre><code>sd-cmd exec <b></b>&lt;namespace&gt;/&lt;name&gt;@&lt;version&gt; &lt;arguments&gt; </code></pre> <ul><li><code>namespace/name</code> - the fully-qualified command name</li> <li><code>version</code> - a semver-compatible format or tag</li> <li><code>arguments</code> - passed directly to the underlying command</li> </ul><p>In this example, Screwdriver will download the command “foobar.sh” from the Store, which is defined by namespace, name, and version, and will execute it with args “-baz sample”. Actual command will be run as:</p> <pre><code>$ /opt/sd/commands/foo/bar/1.0.1/foobar.sh -baz sample </code></pre> <h2>Creating a command</h2> <p>Next, this section covers how to publish your own binary commands or scripts. Commands or scripts must be published using a Screwdriver pipeline. The command will then be available in the same Screwdriver cluster.</p> <p><b>Writing a command yaml</b></p> <p>To create a command, create a repo with a <code>sd-command.yaml</code> file. The file should contain a namespace, name, version, description, maintainer email, format, and a config that depends on a format. Optionally, you can set the <code>usage</code> field, which will replace the default usage set in the documentation in the UI.</p> <p>Example <code>sd-command.yaml</code>:</p> <p>Binary example:</p> <pre><code>namespace: foo # Namespace for the command name: bar # Command name version: '1.0' # Major and Minor version number (patch is automatic), must be a string description: | Lorem ipsum dolor sit amet. usage: | # Optional usage field for documentation purposes sd-cmd exec foo/bar@<b>&lt;VERSION&gt; &lt;OPTION&gt; &lt;TARGET&gt;</b> Options: --baz sample maintainer: foo@bar.com # Maintainer of the command format: binary # Format the command is in (binary, habitat) binary: file: ./foobar.sh # Path to script or binary file from repository root </code></pre> <p>In addition, you can create commands using Habitat packages. You can check the Habitat format in the <a href="https://docs.screwdriver.cd/user-guide/commands">Screwdriver User Guide Page</a>.</p> <p>You can also check out our <a href="https://github.com/screwdriver-cd-test/command-example">example command</a> in the `screwdriver-cd-test` Github organization.</p> <h2>Finding Commands</h2> <p>To find already existing commands, the Commands List Page in the Screwdriver UI shows which ones are available in your Screwdriver cluster. You can find this list by clicking Commands in the dropdown link in the header.</p> <p>You can find the command list by the dropdown link in the header. </p> <img src="https://66.media.tumblr.com/45fdf0a477480dd3eb8aeec9bf8452de/tumblr_inline_pbtivuwSYr1qf05nt_540.png" alt="image"/><img src="./sd-cmd/dropdown.png" alt=""/><p>This action will take you to the Command List Page: </p> <img src="./sd-cmd/commands_list.png" alt=""/><figure data-orig-width="2880" data-orig-height="940" class="tmblr-full"><img src="https://66.media.tumblr.com/119021eba85b87be1aa87ff2e0125dba/tumblr_inline_pcp020DgtS1uvhog4_540.png" alt="image" data-orig-width="2880" data-orig-height="940"/></figure><p>Clicking on the namespace of the command will show you all commands with the same namespace:</p> <figure data-orig-width="2880" data-orig-height="668" class="tmblr-full"><img src="https://66.media.tumblr.com/b013a3fb36a0d468e3263c43d4e40489/tumblr_inline_pcp02jrHAE1uvhog4_540.png" alt="image" data-orig-width="2880" data-orig-height="668"/></figure><p>Clicking on the name of command will show you the Command Detail Page. This page shows the explanation and the usage of the command. If there are multiple versions of a command, you can click on a version listed at the bottom of the page to see that version’s configuration. There’s also a link by the command name to get to the Git repo that the command comes from and an option to delete the command.</p> <p>Example command detail page: </p> <img src="./sd-cmd/command_detail.png" alt=""/><figure data-orig-width="2880" data-orig-height="1538" class="tmblr-full"><img src="https://66.media.tumblr.com/b9d20101699dafcec7e01e8a16663c42/tumblr_inline_pcp03p2cgD1uvhog4_540.png" alt="image" data-orig-width="2880" data-orig-height="1538"/></figure><h2>Compatibility List</h2> <p>For sd-cmd to work, you will need these minimum versions:</p> <ul><li><a href="https://hub.docker.com/r/screwdrivercd/screwdriver/">screwdrivercd/screwdriver</a>: v0.5.387</li> <li><a href="https://hub.docker.com/r/screwdrivercd/launcher/">screwdrivercd/launcher</a>: v4.0.118</li> <li><a href="https://hub.docker.com/r/screwdrivercd/ui/">screwdrivercd/ui</a>: v1.0.311</li> </ul><h2>Contributors</h2> <p>Thanks to the following people for making this feature possible:</p> <ul><li><a href="https://github.com/kumada626">kumada626</a> (from Yahoo! JAPAN)</li> <li><a href="https://github.com/lusol">lusol</a></li> <li><a href="https://github.com/minz1027">minz1027</a></li> <li><a href="https://github.com/stjohnjohnson">stjohnjohnson</a></li> <li><a href="https://github.com/tk3fftk">tk3fftk</a> (from Yahoo! JAPAN)</li> <li><a href="https://github.com/tkyi">tkyi</a></li> <li><a href="https://github.com/wdstar">wdstar</a> (from Yahoo! JAPAN)</li> <li><a href="https://github.com/yokawara">yokawara</a> (from Yahoo! JAPAN)</li> <li><a href="https://github.com/yoshwata">yoshwata</a> (from Yahoo! JAPAN)</li> <li><a href="https://github.com/yuichi10">yuichi10</a> (from Yahoo! JAPAN)</li> </ul><p>Screwdriver is an open-source build automation platform designed for Continuous Delivery.</p> <p>It is built (and used) by Yahoo. Don’t hesitate to reach out if you have questions or would like to contribute: <a href="http://docs.screwdriver.cd/about/support.">http://docs.screwdriver.cd/about/support.</a></p>