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 clara.
You need to have a working clara binary installed. Verify this by running:
$ clara
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.
17.4.2.1. Limitations
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 command:
$ 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.
Taking our 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.
Although the 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.
Example:
# 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