Kamal Aliases
You are an expert in deploying applications with Kamal. Your goal is to turn the long, repetitive kamal commands a user keeps typing into short, memorable shortcuts.
Aliases are shortcuts for Kamal commands. You define them once under the top-level aliases key in config/deploy.yml, and from then on kamal <name> runs the full command for you.
Before You Start
Look at what the user already runs before inventing shortcuts:
- Read
config/deploy.yml. Check whether an aliases: block already exists so you extend it instead of duplicating it.
- Ask which
kamal commands they retype most — a long app exec for a console, a per-destination deploy, a one-off shell command across a role. Those are the best alias candidates.
- Note any destinations in play (
config/deploy.staging.yml, etc.). A destination-specific alias like staging_deploy is a common win.
How Aliases Work
An alias maps a name to everything you would type after kamal. Define it under the root aliases key:
aliases:
console: app exec -i --reuse "bin/rails console"
Now this:
kamal console
runs the command the alias expands to:
kamal app exec -i --reuse "bin/rails console"
| Concept |
Detail |
| Config key |
aliases, at the root of config/deploy.yml |
| Alias value |
The command text that follows kamal (drop the leading kamal) |
| Invocation |
kamal <name> |
| Name characters |
Lowercase letters, numbers, dashes (-), and underscores (_) only |
Step-by-Step Walk-Through
Step 1: Find the command worth shortcutting
Start from a real command the user runs often, for example opening a Rails console:
kamal app exec -i --reuse "bin/rails console"
Step 2: Add it under the aliases key
Copy the command into config/deploy.yml, dropping the leading kamal:
aliases:
console: app exec -i --reuse "bin/rails console"
Step 3: Name it within the rules
Each alias is named and can only contain lowercase letters, numbers, dashes, and underscores. Underscores are allowed here, so stagingdeploy and dbconsole are valid names.
Step 4: Run it
kamal console
Step 5 (optional): Target a destination
An alias can include a destination with the -d flag, which is handy for per-environment shortcuts:
aliases:
staging_deploy: deploy -d staging
kamal staging_deploy
Flags You'll Use in Alias Values
These are the flags that appear in the documented alias examples. Use them inside an alias value exactly as you would on the command line.
| Flag |
Meaning |
-i, --interactive |
Run an interactive command, e.g. a Rails console or bash session |
--reuse |
Run inside the currently running app container instead of a fresh one |
-p, --primary |
Run only on the primary host |
-q, --quiet |
Minimal logging |
-r, --roles |
Run only on the given roles (e.g. -r web) |
-d, --destination |
Use a destination's config (e.g. deploy -d staging reads deploy.staging.yml) |
Documented Examples
aliases:
# Open a Rails console in the currently running container
console: app exec -i --reuse "bin/rails console"
# Print kernel info from the web role's primary host, quietly
uname: app exec -p -q -r web "uname -a"
# Deploy to the staging destination
staging_deploy: deploy -d staging
Each value is just a documented kamal command with its leading kamal removed. Compose your own the same way — for a fuller catalog of practical aliases and the naming rules in detail, see [references/alias-cookbook.md](references/alias-cookbook.md).
For the official documentation, see Aliases.
Related Skills
- config: For the rest of
config/deploy.yml — required keys, destinations, and DRYing up the file with YAML anchors.
- app: For the underlying commands aliases wrap —
kamal app exec, opening a console, and running commands on servers.
