How to use instance command aliases

Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.

See also: Alias, Instance

This guide demonstrates how to create, list, execute and remove aliases for commands running inside an instance.

Create an alias

See also: alias

To create an alias that runs a command on a given instance, use the command alias. The code below uses this command to create an alias lscc that will run the command ls inside an instance crazy-cat:

$ multipass alias crazy-cat:ls lscc

After running this command, the alias lscc is defined as running the command ls on the instance crazy-cat. If the alias name lscc is omitted, the alias name defaults to the name of the command to run (ls in this case).

Working directory mapping

By default, in case the host folder on which executing an alias is mounted on the instance, the working directory on the instance is changed to the mounted directory. This behavior can be avoided when defining the alias using the parameter --no-map-working-directory. For instance:

$ multipass alias crazy-cat:pwd pwdcc --no-map-working-directory

Alias contexts

See also: prefer

Contexts are sets of aliases. While one can safely work with one context, named default, contexts can be useful in some scenarios. For instance, to define aliases with the same name in different instances. One can switch to using another context with multipass prefer secondary. Then, defining an alias in the new context is done in the usual way. The name of the alias can coincide with an already defined one. For example, multipass alias cozy-canary:ls lscc.

List the existing aliases

See also: aliases

To see the list of aliases defined so far, use the aliases command:

$ multipass aliases
Alias   Instance     Command   Context      Working directory
lscc    crazy-cat    ls        default      map
pwdcc   crazy-cat    pwd       default      default
lscc    cozy-canary  ls        secondary*   map

The current context is marked with an asterisk.

The column Working directory tells us on which directory of the host the alias will be executed. The value default means that the alias will be executed in the instance default working directory (normally, /home/ubuntu). The value map means that, in case the host directory from which the user calls the alias is mounted on the instance, the alias will be executed on the mounted directory on the instance. The value will be default only if the --no-map-working-directory argument is present at alias creation.

Execute an alias

There are three ways to execute the alias.

multipass <alias>

The first way of executing an alias is

$ multipass lscc

This shells into the instance cozy-canary, executes ls and returns to the host command-line, as if it was an exec command. Since two aliases have the same name, lscc, the executed one is the one on the current context.

In case of wanting to execute an alias outside the current context, a full-qualified alias name can be used.

multipass default.lscc

Arguments are also supported, provided you separate any options with --:

$ multipass lscc -- -l

or:

$ multipass default.lscc -- -l

<alias>

The second way of running an alias is a two-step process:

Add Multipass alias script folder to system path

First, the Multipass alias script folder to the system path. The instructions to do so are displayed the first time one creates an alias, and vary for each platform. For instance,

$ multipass alias crazy-cat:ls lscc
You'll need to add this to your shell configuration (.bashrc, .zshrc or so) for
aliases to work without prefixing with `multipass`:

PATH="$PATH:/home/user/snap/multipass/common/bin"

In Linux, the shell configuration file must be modified. In most Linux distributions, the shell used by default is bash, which can be configured via the file .bashrc in the users home directory. Any text editor can be used for this, for example doing:

$ nano ~/.bashrc

Once editing the file, the path can be modified by appending at its end a line such as:

export PATH="$PATH:/home/user/snap/multipass/common/bin"

Remember to replace the correct folder by the one given in the output of the Multipass command above and to restart the shell.

In case of using zsh as shell, the file to modify is .zshrc instead of .bashrc; the procedure is the same.

In macOS, the shell configuration file must be modified. The shell used by default is zsh, which can be configured via the file .zshrc in the users home directory. Any text editor can be used for this.

Once editing the file, the path can be modified by appending at its end a line such as:

export PATH="$PATH:/Users/<username>/Library/Application Support/multipass/bin"

Remember to replace the correct folder by the one given in the output of the Multipass command above and to restart the shell.

For Windows, the procedure is a bit more involved. To make the change permanent, use PowerShell to store the old system path, add the alias folder to it, and store the new path.

$old_path = (Get-ItemProperty -Path 'Registry::HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager\Environment' -Name PATH).path
$new_path = “$old_path;C:\Users\<user>\AppData\Local\Multipass\bin”
Set-ItemProperty -Path 'Registry::HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager\Environment' -Name PATH -Value $new_path

Don’t forget to restart your terminal. The folder is now permanently added to your path, Multipass can now execute aliases just invoking their name.

Execute the alias

Once you’ve added the alias folder to the system path, you can execute it directly (without mentioning multipass) as below:

$ lscc

or:

$ default.lscc

This command (given that the path was already added to the system’s path) is equivalent to multipass lscc. Arguments are also supported, without the need for --:

$ lscc -l

Remove an alias

See also: unalias

Finally, to remove the alias lscc, issue:

$ multipass unalias lscc

or:

$ multipass unalias default.lscc

The unalias command accepts many arguments, specifying more than one alias to remove. For example, removing at once aliases lscc and pwdcc is accomplished with:

$ multipass unalias lscc pwdcc

There is also the --all argument, aimed to remove all the defined aliases in the current context at once. Its usage is:

$ multipass unalias --all

An alias is also removed when the instance for which it was defined is purged. This means that multipass delete crazy-cat --purge will also remove the aliases lscc and pwdcc.


Let us know how this worked for you and what you’d like to see next!

Last updated 11 days ago. Help improve this document in the forum.