17.4. Extending clara with Plugins
This guide demonstrates how to install and write extensions for
clara. By thinking of core
clara commands as essential building blocks for interacting with the Clara Deploy SDK, the Clara Deploy SDK administrator can think of plugins as a means of utilizing these building blocks to create more complex behavior. Plugins extend
clara with new sub-commands, allowing for new and custom features not included in the main distribution of
You need to have a working
clara binary installed. Verify this by running:
A plugin is nothing more than a standalone executable file, who name begins with
clara-. To install a plugin, simply move this executable file to anywhere in your PATH.
It is currently not possible to create plugins that overwrite exiting
clara commands. For example, creating a plugin
clara-version will cause that plugin to never be executed as the existing
clara version command will always take precedence over it. Due to this limitation, it is also not possible to use plugins to add new subcommands to existing
clara actions/commands. For example, add a subcommand
clara version foo by naming your plugin
clara-version-foo will cause that plugin to be ignored.
You can write a plugin in any programming language or scripts that allows you to write command-line commands.
There is no plugin installation or pre-loading required. Plugin executables recieve the inherited environment from the
clara binary. A plugin determines which command path it wishes to implement based on its name. For example, a plugin wanting to provide a new command
clara hello would simply be named
clara-hello, and live somewhere in the user’s PATH.
#!/bin/bash # Optional argument handling if [[ "$1" == "version" ]] then echo "1.0.0" exit 0 fi echo "hello world"
To use the above plugin, simply make it executable:
$ sudo chmod +x ./clara-hello
and place it anywhere in your PATH:
$ sudo mv ./clara-hello /usr/local/bin
You may now invoke your plugin as a
$ clara hello hello world
All args and flags are passed as-is to the executable:
$ clara hello version 1.0.0
Additionally, the first argument that is passed to a plugin will always be the full path to the location where it was invoked ($0 would equal /usr/local/bin/clara-hello in our example above)
As seen in the example above, a plugin determines the command path this it will implement based on its filename. Every sub-command in the command path that a plugin targets, is separated by a dash (
-). For example, a plugin that wishes to be invoked whenever the command
clara foo bar baz is invoked by the user would have the filename
clara-foo-bar-baz plugin fromt he above scenario, we further explore additional cases where users invoke our plugin while providing additional flags and arguments. For example, in a situation where a user invokes the command
clara foo bar baz arg1 --flag=value arg2, the plugin mechanism will first try to find the plugin with the longest possible name, which in this case would be
clara-foo-bar-baz-arg1. Upon not finding that plugin, it then treates the last dash-separated value as an argument (
arg1 in this case) and attempts to find the next longest possible name
clara-foo-bar-baz. Upon finding a plugin with this name, it then invokes that plugin, passing all args and flags after its name to the plugin executable.
clara plugin mechanism uses the dash (
-) in the plugin filenames to separate the sequance of sub-commands processed by the plugin, it is still possible to create a plugin command containing dashes in its commandline invocation by using underscores (
_) in its filesname.
# Create a plugin containing an unerscore in its filename $ echo '#!/bin/bash\n\necho "I am a plugin with a dash in my name"' > ./clara-foo-bar # Make the plugin executable $ sudo chmod +x ./clara-foo-bar # Move the plugin into your PATH $ sudo mv ./clara-foo-bar /usr/local/bin # Run the plugin $ clara foo-bar I am a plugin with a dash in my name
Note: the introduction of underscores to a plugin filename does not prevent us from having commands such as
clara foo_bar. The command from the above example can be invoked using either a dash (
-) or an underscore (
# Run our plugin with a dash $ clara foo-bar I am a plugin with a dash in my name # Run our plugin with an underscore $ clara foo_bar I am a plugin with a dash in my name
To uninstall a plugin, simply remove it from PATH:
# We can "uninstall" a plugin by simply removing it from our PATH $ sudo rm /usr/local/bin/clara-hello