✨ New commands

📄 Add a new command file

Create a new bash script with the file extension .sh under your user directory. E.g.:

Add the bash shebang at the beginning of the file to help your editor identifying the correct shell:

#!/usr/bin/env bash

🔤 Define your new command

Valet looks for a specific YAML formatted string to read command properties.

A simple example is:

: "---
command: hello-world
function: helloWorld
shortDescription: A dummy command.
description: |-
  This command says hello world.
---"

In the example above, we need to define a bash function named helloWorld in the same file as the command properties (see next step). When running valet hello-world, this function will be called.

A list of all the available command properties can be found in this section.

If your new command name contains one or more spaces, you are defining a sub command. E.g. sub cmd defines a command cmd which is a sub command of the sub command. It can be useful to regroup commands. Valet will show a menu for the command valet sub which displays only the sub commands of sub.

For more examples, take a look at the showcase command definitions.

Alternatively, you can add a new command definition using bash comments and the following format:

##<<VALET_COMMAND
# command: hello-world
# function: helloWorld
# shortDescription: A dummy command.
# description: |-
#   This command says hello world.
##VALET_COMMAND

✒️ Implement your command

Once the command properties are set, the next step is to implement the command function.

A minimal command function has the following content (note that the function name matches the example of the previous step: change it to your function name).

1
2
3
4

function helloWorld() {
  core::parseArguments "$@" && eval "${RETURNED_VALUE}"
  core::checkParseResults "${help:-}" "${parsingErrors:-}"
}

Explanations:

• core::parseArguments "$@" is a core function of Valet which parses the input argument (i.e. $@) and returns a string in the global variable RETURNED_VALUE which can be evaluated to set local variables corresponding to arguments and options. See the function help in the core library documentation page.
• eval "${RETURNED_VALUE}" evaluates the output string of the parsing function which sets local variables.
• core::checkParseResults "${help:-}" "${parsingErrors:-}" will check if the local variable help is true, which corresponds to the option --help passed to the function, in which case it will display the function help and stop its execution. It will also check if the local variable parsingErrors is not empty, which indicates that the parsing function encountered input errors: the function execution is also stopped with parsing errors shown to the user.

After these two mandatory lines, you can implement your function using local variables defined for you depending on the user inputs. You are guaranteed that the inputs are valid.

A command example

Find below the complete definition of a example command that can take an option --my-option and requires one argument my-argument.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

: "---
command: example
function: example
shortDescription: An example command
description: |-
  Will display the passed argument and option.
arguments:
- name: my-argument
  description: |-
    First argument.
options:
- name: -o, --my-option
  description: |-
    First option.
---"
function example() {
  local myOption myArgument
  # parse the arguments of the command and evaluates to local variables
  core::parseArguments "$@" && eval "${RETURNED_VALUE}"
  # check if we need to exit because there was some inputs errors or if we need to just display the help
  core::checkParseResults "${help:-}" "${parsingErrors:-}"

  # use options and arguments
  echo "${myOption} and ${myArgument}"
}

Executing valet example --my-option opt1 arg1 will display opt1 and arg1 in the standard output:

• An option named -o, --my-option will translate to a local variable myOption (takes the first long name found and convert it to camel case).
• An argument named my-argument will translate to a local variable myArgument (camel case).

Check the command properties section for more details on how arguments and options are translated to local variables.

Understand the parser

The function core::parseArguments "$@" will return a string that can be evaluated to define the parsed options and arguments as local variables.

With the command example above, assuming that the user input is valet example --thing --my-option opt1 arg1 the content of the global variable RETURNED_VALUE would be:

local myoptions="opt1"
localmyArgument="arg1"
local parsingErrors="Unknown option '--thing'"

The parsingErrors variable contains the parser error: here we passed an option that is unknown for this command. Calling core::checkParseResults "${help:-}" "${parsingErrors:-}" will print that parsing error message to the user and exit the program.

Access Valet library functions

In the function of a command, you have access by default to a set of Valet functions:

• All the core functions, i.e. function starting with core::. See the core library documentation page for more available functions.
• All the log functions, i.e. function starting with log::. See the core library documentation page for more available functions.

More useful function are accessible by including a Valet library in your script or command function. For this, you need to source the library that you need, e.g.:

source string

You can find a list of all the libraries here.

Error handling and return values

Although you can simply exit from a command function, it is recommended to:

• ✅ return 0 if all went well.
• ❌ core::fail "My error message" if something went wrong. This will exit the program with code 1 and print your error to the user. You can use core::failWithCode if you need to return a particular exit code.

The options set -Eeu -o pipefail have the following meaning:

• -e: This option instructs the shell to immediately exit if any command has a non-zero exit status.
• -u: This option instructs the shell to immediately exit if it tries to use an unset variable.
• -o pipefail: This option prevents errors in a pipeline from being masked.
• -E: Any trap on ERR is inherited by shell functions, command substitutions, and commands executed in a subshell environment. The ERR trap is normally not inherited in such cases.

If you expect a statement to fail but want to continue the execution, catch the exit code:

local exitCode=0
thingThatReturns1 || exitCode=$?
if [[ ${exitCode} != 0 ]]; echo "do something if the command failed?..."; fi

Or simply discard the error:

thingThatReturns1 || :

If you use a variable that could be unset, provide a default value:

echo "${myUnsureVariable:-default value}"

Implementation tips

The section performance tips gives you pointer to write scripts that are fast to execute.

You don’t have to remember all the Valet functions or look at the documentation every 5s: check this section to learn how to configure VScode to have autocompletion on all Valet functions.

🧪 (optional) Test your command

Please check the test command section.

🛠️ Rebuild valet menu

You will not find your command in the Valet menu nor will you be able to execute it immediately after adding (or modifying) its definition.

You first need to let Valet “re-index” all your commands by executing the self build.

The build process consists of updating the ~/.valet.d/commands file by extracting all the commands definitions from your scripts. This file defines variables which are used internally by Valet.

During the build, all files matching *.sh will be read by Valet to look for command definitions, and the search is recursive. Directories named tests.d or hidden directory (starting with a .) will be ignored. Consider these rules to lower the build time if it becomes too important.