✨ Create a command

🧑‍💻 Setup your development environment

The section working on bash will help you set up a coding environment for bash.

Open your existing extension directory or create a new one.

📄 Add a new command file

Run the following command to create a new command file named my-command.sh in the commands.d directory of your extension:

Replace my-command with the name of your command.

valet self add-command my-command

Alternatively, create the file manually.

🔤 Define your new command

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

A simple example is:

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

The command properties must start with a line containing only : <<"COMMAND_YAML" and end with a line containing only COMMAND_YAML.

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 here:

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.

Sub commands 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 comment the whole command properties block like so:

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

The only advantage would be to have a documentation for your command function that is understandable by your IDE.

✒️ Implement your command

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

🧪 (optional) Test your command

You can optionally test your command to ensure future non-regressions of its behavior:

🛠️ 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:

valet self build

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