- bash commands
- python commands
- parameters, alias etc
- how to structure your commands
- batteries included
- project
- flow
- is it a tool or a library?
- publish my code
- plugins
Here are some use cases that hopefully will have the following properties:
- provide a better idea of what clk is capable of than a simple description,
- show some common pattern that emerged when using clk,
- give examples of real life uses of clk, giving hints about when it might be useful,
bash commands
The basics are covered here. To get more into how to provide parameters to your command, read that one. If your parameters are too complicated to be simply parsed, follow the idea of this use case.
If you find out that your bash command starts to become quite big, read this to find out how to split your code.
Most of my bash commands start with simple aliases. You can read more about this way of thinking in here.
python commands
The basics of creating python commands are covered here. For more advanced patterns involving dynamic parameters and exposed classes, see the section on how to structure your commands.
parameters, alias etc
Sometimes, you might want to have some control about how the arguments of the command lines are evaluated, take a look at this use case to know more about them.
If you want to share configuration between a Python group and its bash subcommands through environment variables, see the multi-environment deployment tool example.
For an example of using aliases with templated environment variables to create flexible workflows, see the podcast automation example.
If you want to persist command options so you don’t have to repeat them, and optionally override them per-project, see the cloud provider CLI wrapper example.
When parameters become tedious because you need to set the same option on many commands, consider using values to set semantic defaults instead. This use case also explains the difference between syntactic (parameters) and semantic (values) configuration, with a comparison to git config.
how to structure your commands
To create powerful, dynamic command line tools that provide the best completion possible, see this pattern for writing your commands. In case you have some issues, you might want to look at the advanced use cases.
commands as first order objects
Sometimes, you create commands not only to be called directly, but to be used as basis to build greater commands.
This example of an ethereum local environment dev tool shows how to plug clk commands as parameters in other commands.
ipfs name publish shows how to use clk bash commands to create the completion for other commands.
batteries included
Like python, clk try hard to provide most of the things you want in a generic command line tool.
In shell command, the library included by default (called _clk.sh) provides some useful helpers to help you create a nice and friendly command, despite, well… bash.
When you want to provide some choices in command, it might be worthwhile to look at those examples.
To cache some computation to disk, see the web scrapping use case.
We put a lot of useful logic in clk.lib but did not document much as of now. This is the current state of this documentation.
Some commands might need to use secret, here is how we implement that.
project
Sometimes, you want to gather some commands or configuration in a folder. We call that folder a project.
If you want to do that to, you might want to read this.
flow
When your commands need to be connected and called in a sequence, we call that a flow.
clk does not want to compete with flow tools, like nodered, but it helps having a basic flow handling from time to time, like when you have a 3D printing flow.
is it a tool or a library?
If you don’t want to use the clk command line tool, you can roll your own.
publish my code
In that case, you would like to take a look at how to create your own extensions.
plugins
In case clk does not fit your use cases totally, and you want to dynamically monkey-patch its internal (at your own risks), you can use the plugin mechanism.
We describe here how a command could be added along with some modification of behavior of clk invoke system. This is almost dark magic, so we don’t actually expect you to need this, but it has been useful in a few very specific situations.