Taming Command Line Chaos: Macros to the Rescue!
Raise your hand if you’ve ever stared blankly at a terminal, trying to remember the exact incantation you used to conjure an SSL certificate or spin up a virtual machine in the cloud. Command Line Interfaces (CLIs), while powerful, can be notoriously cryptic, especially with complex tools. Remembering all those flags and arguments? Let’s just say it’s not everyone’s idea of a good time.
The Bash Spaghetti Nightmare
If you’ve ever worked with a CLI with a laundry list of arguments (we’re talking 44 in the case of our own tool, Rot), you know the struggle is real. To wrangle these beasts, we’ve all resorted to wrapping commands in shell scripts or aliases—the infamous “bash spaghetti.” This approach may solve the repeatability problem, but it introduces new ones:
- Argument Wrestling: Ever tried to figure out if a bash variable is a string or an array? Or when to quote something with spaces? It’s a battle.
- Discoverability Disaster: Your beautifully crafted CLI tool is now hidden behind an unsightly bash script. Not the most welcoming first impression.
A Blast from the Past: Macros as the Solution
What if we told you there’s a solution that’s been around since the early days of computing? Enter macros—a way to create reusable commands. We’ve taken this old-school concept and baked it right into our CLI configuration.
Let’s see how this works with Rot. Here’s the default usage:
$ rot
Usage: rot <global flags> [command/macro]
Secure Secrets Management for the Modern Sysadmin
By using this software you agree to the End-User License Agreement (EULA) for Rot. To view the EULA, type `rot eula`.
Commands:
alg
Show algorithms Rot understands.
autocomplete
Source this argument using `source <(rot autocomplete)` to add autocomplete entries.
base64 <command flags> [input value or - for stdin]
Encode/decode a base64 value or stdin and output to stdout.
Command Flags:
-d
Decode base64 (default: encode)
-r
Raw/no padding (default: padding)
-u
URL encoding (default: standard encoding)
...
Now, let’s add a macro for the base64 command to our rot.jsonnet configuration:
{
cli: {
macros: {
b64: {
argumentsRequired: [
'input value or - for stdin',
],
flags: {
d: {
usage: 'Decode base64 raw'
},
},
template: 'base64 -r {{ if getFlag "d" }}-d{{ end }} {{ getArg 1 }}',
usage: 'Encode or decode a string using base64 raw encoding.',
},
},
},
}
Now, check out the updated usage:
$ rot
Usage: rot <global flags> [command/macro]
Secure Secrets Management for the Modern Sysadmin
By using this software you agree to the End-User License Agreement (EULA) for Rot. To view the EULA, type `rot eula`.
Macros:
b64 <macro flags> [input value or - for stdin]
Encode or decode a string using base64 raw encoding
Macro Flags:
-d
Decode base64
Commands:
alg
Show algorithms Rot understands.
autocomplete
Source this argument using `source <(rot autocomplete)` to add autocomplete entries.
base64 <command flags> [input value or - for stdin]
Encode/decode a base64 value or stdin and output to stdout.
Command Flags:
-d
Decode base64 (default: encode)
-r
Raw/no padding (default: padding)
-u
URL encoding (default: standard encoding)
...
Boom! Our custom macro is now part of the official usage. And the best part? Rot will even warn you if you forget any required arguments:
$ rot b64
ERROR missing arguments: [input value or - for stdin]
Usage: rot <global flags> b64 <macro flags> [input value or - for stdin]
Encode or decode a string using base64 raw encoding
Macro Flags:
-d
Decode base64
Global Flags:
...
Macros: Your CLI’s New Best Friend
By embracing macros, you can transform your complex CLIs into user-friendly powerhouses. Say goodbye to bash spaghetti and hello to streamlined workflows. If you’re curious to learn more about how we’re using macros in Rot and our other tools, check out our documentation.