Commandline usage ¶

RKD command-line usage is highly inspired by GNU Make and Gradle, but it has its own extended possibilities to make your scripts smaller and more readable.

Tasks are prefixed always with “:”.
Each task can handle it’s own arguments (unique in RKD)
“@” allows to propagate arguments to next tasks (unique in RKD)

Tasks arguments usage in shell and in scripts ¶

Executing multiple tasks in one command:

./rkdw :task1 :task2

Multiple tasks with different switches:

./rkdw :task1 --hello  :task2 --world --become=root

Second task will run as root user, additionally with --world parameter.

Tasks sharing the same switches

Both tasks will receive switch “–hello”

         # expands to:
#  :task1 --hello
#  :task2 --hello
./rkdw @ --hello :task1 :task2

# handy, huh?

        

Advanced usage of shared switches

Operator “@” can set switches anytime, it can also clear or replace switches in NEXT TASKS .

         # expands to:
#   :task1 --hello
#   :task2 --hello
#   :task3
#   :task4 --world
#   :task5 --world
./rkdw @ --hello :task1 :task2 @ :task3 @ --world :task4 :task5

        

Written as a pipeline (regular bash syntax)

It’s exactly the same example as above, but written multiline. It’s recommended to write multiline commands if they are longer.

         ./rkdw @ --hello \
    :task1 \
    :task2 \
    @
    :task3 \
    @ --world \
    :task4 \
    :task5

        

Arguments ¶

Each task has it’s own arguments parsing and –help method

         # see a list of commandline switches
./rkdw :task1 --help

# increase log level
./rkdw :task1 --log-level debug

# log output to file
./rkdw :task1 --log-to-file=/tmp/task1.log

# change user for task execution time
./rkdw :task1 --become=root

        

Global commandline switches

To apply default, global error level use a switch before all tasks.

         ./rkdw --log-level=debug :task1 :task2

# alternatively (changes log level on earlier stage than argument parsing)
RKD_SYS_LOG_LEVEL=debug ./rkdw :task1 :task2

# or like shown in 'Tasks arguments usage in shell and in scripts' - any commandline switches
# can be propagated, including RKD internal switches
./rkdw @ --log-level=debug --task-workdir=/tmp :task1 :task2

        

Advanced: Blocks for error handling ¶

Blocks allow to retry single failed task, or a group of tasks, execute a failure or rescue task.

Tip

Blocks cannot be nested.

Retry a task - @retry

Retry task until it will return success, up to defined retries. If there are multiple tasks, then a single task is repeated, not a whole block.

./rkdw '{@retry 3}' :unstable-task '{/@}'

Retry a block (set of tasks) - @retry-block

Works very similar to @retry, but in case, when at least one task fails - all tasks in the block are repeated.

./rkdw '{@retry-block 3}' :unstable-task :task2 '{/@}'

Rescue - @rescue

When a failure happens in any of tasks, then those tasks are interrupted and a rollback task is executed. Whole block status depends on the rollback task status. After a successful rollback execution next tasks from outside of the blocks are normally executed.

         ./rkdw :db:shutdown :db:backup '{@rescue :db:restore}' :db:upgrade '{/@}' :db:start

        

Error - @error

When at least one task fails, then a error task is notified and the execution is stopped.

./rkdw '{@error :notify "Task failed!"}' :some-task :some-other-task '{/@}'