Basics

Installating

To install hyperpotamus, you should already have node.js and npm installed.

Once you have npm installed, execute:

npm install -g hyperpotamus

NOTE: If you are on a Mac or Linux machine, you may have to use

sudo npm install -g hyperpotamus

This will install hyperpotamus and the command-line interface (cli) into your path. Once you have hyperpotamus installed, you should be able to check the current version by executing the cli with the --version option:

hyperpotamus --version

Updating

To update to the latest version of hyperpotamus, execute:

npm update -g hyperpotamus

Uninstalling

npm uninstall -h hyperpotamus

Executing Scripts

To execute a script, simple run hyperpotamus and pass it the name of your script file.

hyperpotamus my_script.yml

Help with Command-line Options

There are a lot of command-line options that you can use to control hyperpotamus. To display the help information, run:

hyperpotamus --help

or more concisely, you can run hyperpotamus with no options or parameters to get the same help.

Making a script self-executable

This is not necessarily a hyperpotamus feature, but it is still a nice convenience if you are running on MacOS or any other *nix variant. You can use your shell functionality to make your scripts self-executable with the following steps:

1. Add a shebang directive on the first line of your script #!/usr/bin/env hyperpotamus

2. Mark your script as executable chmod +x my_script.yml

3. Now you can run your script with ./my_script.yml [additional options]

You can also add some additional options to the #! line if there are specific options that should always be used with that particular script.

Logging

When you run a script, you may not see any output, depending upon what the script does. To see information about what hyperpotamus is doing behind the scenes, you can add a --verbose flag to the command-line. Adding multiple --verbose flags (up to 3) will increase the amount of detail that shows up. -v, -vv, or -vvv are shortcuts to increase the logging level.

Logging can be helpful when debugging your scripts and when trying to figure out what value a particular variable holds or why a specific action was processed.

Stopping a script

When you run a script, you can press Ctrl-C to request hyperpotamus to stop processing any future script executions. If you are running a script multiple times, for example with --loop or --csv, then hyperpotamus will finish the current iteration of the script, but no new iterations will be started. Hyperpotamus will display a message telling you that it will attempt a graceful shutdown. If you want to interrupt processing immediately, forcing the script to terminate before it completes, press Ctrl-C a second time.

Getting Help

For help with command-line options for hyperpotamus, run the command with the --help flag. Hyperpotamus will show you a menu with descriptions about available commands.

For overall help and training, this wiki is the best place to look. There are tutorials and guides as well as reference materials to document specific actions, pipes, and interpolation.