Quick Start

In this tutorial, we will integrate our first command to command launcher

Preparation #

If you want to use the default command launcher binary name (cola): install command launcher following the guide Binary install. Or if you prefer a different binary name, build command launcher from source: Build from source

In Criteo, we call it cdt, (Criteo Dev Toolkit)

In this tutorial, we will use the binary name cola.

To check your command launcher installation, run following command:

cola config

It should list all your configurations. The important ones for this tutorial is the following:

dropin_folder                    : [command launcher home]/dropins
local_command_repository_dirname : [command launcher home]/current

Default command launcher home:

For example, on my Macbook (with user criteo), my command launcher home is /Users/criteo/.cola

Command launcher also provide auto-completion feature to all managed commands, you only need to setup auto-completion once: setup auto-completion

Let’s build a command #

If you already have a command you can skip this step. Command launcher is technology agnostic to your command. You can build your command in any tech stack that suits your use case. In this tutorial, let’s build a simple “Hello World” command line tool with bash scripts.

In command launcher, commands are packaged into packages. Let’s first create a package for our newly created command:

cd $HOME/.cola/dropins
mkdir my-first-package
cd my-first-package

Create a script file first-command-launcher-cmd.sh, which prints greeting message according to the language

#!/bin/bash

LANG=${LANG:-en}

if [ $LANG == "fr" ]; then
  echo "Bonjour! $1"
  exit 0
else
  echo "Hello! $1"
  exit 0
fi

You can run it directly as a normal bash script:

$ ./first-command-launcher-cmd.sh "command launcher"
Hello! command launcher

$ LANG=fr ./first-command-launcher-cmd.sh "command launcher"
Bonjour! command launcher

Prepare a minimal manifest.mf #

Now we have a working command/script. To make command launcher aware of it, we need to create a manifest file (in JSON or YAML format) at the root folder of the package:

manifest.mf

pkgName: my-first-package
version: 0.0.1
cmds:
  - name: greeting
    type: executable
    executable: "{{.PackageDir}}/first-command-launcher-cmd.sh"

That’s it! Your command has been integrated to command launcher with a subcommand named greeting, to test it:

$ cola greeting "command launcher"
Hello! command launcher

$ LANG=fr cola greeting "command launcher"
Bonjour! command launcher

Command launcher will pass all the environment variables, arguments to itself to your command.

Tell more about your command to command launcher #

We can go even further to turn our bash scripts into a native-like program. Let’s add extra information in the manifest, and make some improvements of its user interface:

• the short and long description
• some examples
• use a flag to take language input instead of environment variable LANG

pkgName: my-first-package
version: 0.0.2
cmds:
  name: greeting
  type: executable
  short: Simple greeting command
  executable: "{{.PackageDir}}/first-command-launcher-cmd.sh"
  requiredFlags:
    - "language\t greeting language"
  examples:
    - scenario: Greeting with default language
      cmd: greeting [name]
    - scenario: Specify the greeting language
      cmd: greeting --language fr [name]
  checkFlags: true

The above manifest tells command launcher that the greeting command requires a flags called language, and let command launcher to check the flags before calling the script

Now when you run the greeting command with -h or --help, you will get a nice help message like a native command:

$ cola greeting -h
Usage:
  cola greeting [flags]

Examples:
  # Greeting with default language
  greeting [name]

  # Specify the greeting language
  greeting --language fr [name]


Flags:
  -h, --help              help for greeting
      --language string   greeting language

But how can our script get the language passed from the --language flag? Command launcher passes an environment variable to your script with the name CDT_FLAG_LANGUAGE (More details see checkFlags). You can modify your script to get the language from it like so:

#!/bin/bash

LANG=${COLA_FLAG_LANGUAGE:-en}

if [ $LANG == "fr" ]; then
  echo "Bonjour! $1"
  exit 0
else
  echo "Hello! $1"
  exit 0
fi

Now we have turned our bash script into a native-like command.

Auto-completion #

Command launcher will automatically enable auto-completion for your command. Subcommand, flags, arguments will will be auto-completed when you type [TAB][TAB], for example:

$ cola g[TAB][TAB]
greeting - Simple greeting command
grepx    - Enhanced grep command

$ cola greeting --[TAB][TAB]
$ cola greeting --language