Usage
Starting a Linux instance
Run limactl start <INSTANCE>
to create and start the first instance.
The <INSTANCE>
name defaults to “default”.
$ limactl start
? Creating an instance "default" [Use arrows to move, type to filter]
> Proceed with the current configuration
Open an editor to review or modify the current configuration
Choose another template (docker, podman, archlinux, fedora, ...)
Exit
...
INFO[0029] READY. Run `lima` to open the shell.
Choose Proceed with the current configuration
, and wait until “READY” to be printed on the host terminal.
For automation, --tty=false
flag can be used for disabling the interactive user interface.
Customization
To create an instance “default” from a template “docker”:
limactl create --name=default template://docker
limactl start default
See also the command reference:
Executing Linux commands
Run limactl shell <INSTANCE> <COMMAND>
to launch <COMMAND>
on the VM:
limactl shell default uname -a
See also the command reference:
For the “default” instance, this command can be shortened as lima <COMMAND>
.
lima uname -a
The lima
command also accepts the instance name as the environment variable $LIMA_INSTANCE
.
SSH can be used too:
$ limactl ls --format='{{.SSHConfigFile}}' default
/Users/example/.lima/default/ssh.config
$ ssh -F /Users/example/.lima/default/ssh.config lima-default
Using SSH without the -F
flag
To connect directly without specifying the config file, add this to your ~/.ssh/config
:
Include ~/.lima/*/ssh.config
Then you can connect directly:
ssh lima-default
Command Aliasing (Plugin System)
Lima supports a plugin-like command aliasing system similar to git
, kubectl
, and docker
. When you run a limactl
command that doesn’t exist, Lima will automatically look for an external program named limactl-<command>
in your system’s PATH.
Creating Custom Aliases
To create a custom alias, create an executable script with the name limactl-<alias>
and place it somewhere in your PATH.
Example: Creating a ps
alias for listing instances
Create a script called
limactl-ps
:#!/bin/sh # Show instances in a compact format limactl list --format table "$@"
Make it executable and place it in your PATH:
chmod +x limactl-ps sudo mv limactl-ps /usr/local/bin/
Now you can use it:
limactl ps # Shows instances in table format limactl ps --quiet # Shows only instance names
Example: Creating an sh
alias
#!/bin/sh
# limactl-sh - Connect to an instance shell
limactl shell "$@"
After creating this alias:
limactl sh default # Equivalent to: limactl shell default
limactl sh myinstance bash # Equivalent to: limactl shell myinstance bash
How It Works
- When you run
limactl <unknown-command>
, Lima first tries to find a built-in command - If no built-in command is found, Lima searches for
limactl-<unknown-command>
in your PATH - If found, Lima executes the external program and passes all remaining arguments to it
- If not found, Lima shows the standard “unknown command” error
This system allows you to:
- Create personal shortcuts and aliases
- Extend Lima’s functionality without modifying the core application
- Share custom commands with your team by distributing scripts
Shell completion
- To enable bash completion, add
source <(limactl completion bash)
to~/.bash_profile
. - To enable zsh completion, see
limactl completion zsh --help