⚙️ Command properties

This page describes the properties available to define a command.

Here is a definition example that uses all the properties:

 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
26
27

command: command
function: functionName
shortDescription: A short sentence.
description: |-
  A long description that can use ⌜quotes⌝.  
sudo: false
hideInMenu: false
arguments:
- name: firstArg
  description: |-
    First argument.    
- name: more...
  description: |-
    Will be an an array of strings.    
options:
- name: -o, --option1
  description: |-
    First option.    
  noEnvironmentVariable: true
- name: -2, --this-is-option2 <level>
  description: |-
    An option with a value.    
  noEnvironmentVariable: false
examples:
- name: command -o -2 value1 arg1 more1 more2
  description: |-
    Call command with option1, option2 and some arguments.    

You can check the showcase commands to get definition examples.

🫚 Top level properties

The available properties are:

✔️ command

The name with which your command can be called by the user. E.g. mycmd will be accessible with valet mycmd.

✔️ function

The name of the function that corresponds to the command. This is the function that will be called by Valet when the user executes this command.

✔️ shortDescription

Shortly describe your command. This will appear next to your command name in the valet menu.

This should be a single, short, line.

✔️ description

Long description of your command and its purpose. It will display when getting the help/usage on the command using valet help command or valet command --help.

sudo

Set to true if you intend to use sudo in your command. It will define a SUDO variable that you should instead (e.g. ${SUDO} cp stuff /usr/bin/local/stuff instead of sudo cp stuff /usr/bin/local/stuff).

The idea is to make your command compatible for systems with and without sudo. The variable SUDO will be defined as empty if the sudo command can not be found.

If true, it will prompt the user for sudo password before executing the command.

hideInMenu

Set to true if you do not want this command to appear in the Valet menu. The command will still get listed in the help/usage of valet.

arguments

A list of arguments for your command. See Arguments for the details of an argument.

options

A list of options for your command. See Options for the details of an option.

By definition, an option is optional (i.e. it is not mandatory like an argument). If you expect an option to be defined, then it is an argument.

examples

A list of examples for your command. See Examples for the details of an example.

They are used exclusively in the command help/usage text.

💬 Arguments

Arguments are parsed in the order given in the list of arguments for the command definition.

✔️ name

The argument name.

When calling core::parseArguments the argument will be parsed to local variable which name correspond to the camelCase equivalent of its name.

Moreover, the name can be suffixed to enable extra features:

• The name ends with ... then the argument will be defined as an array and the variable will hold all remaining arguments. Only the last argument can be suffixed like that.
• The name ends with ? then the argument is optional (otherwise there will be an error if the user does not provide a value). Only the last arguments can be suffixed like that.
• The name ends with ?... then the argument is an optional array (combination of the two above).

Example of a argument names and their corresponding variables:

• my-arg1 → local myArg1
• files... → local -a files
• commands?... → local -a commands

✔️ description

The description for this argument. It will be used to display the help/usage of the command.

🎚️ Options

✔️ name

The option name(s). An option can have one or more long name and up to one short name. Each name is separated with , .

• A short name is composed of a single hyphen and a single letter. E.g. -o or -b.
• A long name is composed of two hyphens then a valid string (alpha numerical that can contain hyphens). E.g. --option or --my-great-option.

An option can be a simple true/false flag or it can hold a user value:

• If the option ends with <something>, then the option will hold a value passed by the user.
• Otherwise, the option will be a simple flag and will be equal to true if the user passed the option, false otherwise.

When calling core::parseArguments options will be parsed to local variable which name correspond to the camelCase equivalent of the first long option name.

Example of a valid option names and their corresponding variable name:

• -x, --profiling → local profiling
• --thing → local thing
• -l, --log-level, --log <level> → local logLevel

Short names can be grouped together when calling the command. E.g. -fsL is equivalent to -f -s -L or equivalent to the long name options --force --silent --follow.

✔️ description

The description for this option. It will be used to display the help/usage of the command.

noEnvironmentVariable

By default, an option that can have a value (e.g. --option <something>) will be parsed to a local variable which default to a global variable if not value was passed by the user.

For instance, the option --option1 will be parsed to the local variable option1 with the following definition: local option1="${VALET_OPTION1:-}". This allows to define options through environment variable.

This behavior can be changed by setting noEnvironmentVariable: true which will always make the local variable for the option empty.

default

The default value to give to the local variable parsed from the option. The global variable will take precedence (see noEnvironmentVariable).

The local variable will be defined like this: local option1="${VALET_OPTION1:-"default value"}". Where default value is the value of this option.

🎈 Examples

Examples are used in the command help/usage and let the user quickly understand how to use the command.

✔️ name

The command for this example.

You should not include valet as it will be prepended automatically. If you do not want to prepend it, start the name with ! (useful to illustrate a more complex command line).

✔️ description

The description for this example.