Aliases
managing snaps for users for administrators for app developers
An alias is a second command name for one app of a snap. Manual aliases are set with snap alias. Automatic aliases are listed in the snap-declaration that the store issues and are enabled or disabled together for each snap. One name can be enabled for one snap at a time and snap prefer moves the conflicting names to the snap you choose.
On the map: administration district
01 A shorter name for a long command
snap alias photo-editor.convert pconv adds a second name for one app. Manual aliases are yours; automatic aliases come from the store with the snap. The convert app of photo-editor is invented for this deck.
You convert photos from the terminal all day, and every time you type photo-editor.convert. Could that be shorter? Snap commands carry the snap's name, so that two snaps can't collide. That's safe, and long. An alias gives one app a second name, like a nickname; the full name still works. Snap alias takes two arguments: the app, and the name you want. Snapd prints what it added. From now on, pconv runs the same app with the same confinement. That's a manual alias, and it's yours. The other kind is automatic: the store lists it for the snap, and snapd enables it at install.
02 An alias is a symlink for administrators for app developers
The alias is a symlink pconv -> photo-editor.convert in the snap binaries directory (/snap/bin on Ubuntu), plus a completion symlink when the app has a completer. Removing the snap removes its links.
So what did snapd change when it said Added? One thing, and you can look at it. In the directory where every snap command lives, there's now a link called pconv. Its target is the name photo-editor.convert, nothing more. So the alias always runs whatever revision is current. If the app has a bash completer, the alias gets a completion link too. Nothing is written into the snap itself. And when you remove photo editor, its links go with it.
03 Reading snap aliases
snap aliases [<snap>] prints Command, Alias and Notes. Notes is - for an enabled automatic alias, manual, disabled, or manual,override. The published documentation calls automatic aliases default aliases.
A week later you can't remember which short names you made and which came with the snap. Snap aliases tells you. It prints three columns: the command, the alias, and a note. A dash means an automatic alias that's enabled. Manual is one you made. Now run snap unalias photo-editor. Convert reads disabled: known, but switched off, and pconv is simply gone, because a manual alias has no off position. Automatic aliases switch per snap: all on, or all off. And if you give your own alias the name of an automatic one, yours is used, and the note says manual, override.
04 Automatic aliases come from the store for app developers for administrators
Automatic aliases are the aliases header of the snap-declaration: name and target pairs. snapd recomputes them in the set-auto-aliases task at install and refresh. The older auto-aliases header is still read as a fallback.
Say you publish photo editor and you'd like convert to work straight after install. Where do you write that down? Not in snap.yaml, and that's deliberate. Short names are shared by everyone on the system, so the store decides who gets one. The answer travels in the snap-declaration, as a list of pairs: a name, and the app it targets. At install and at every refresh, snapd reads that list and works out the snap's aliases, keeping your manual ones. An entry whose app is missing, or is a daemon, is skipped. And a snap you built and installed locally has no declaration, so it gets none.
05 One name, one snap
An alias already enabled for another snap is refused: cannot enable alias "convert" for "image-tools", already enabled for "photo-editor". An alias also cannot equal an installed snap's name or begin with <snap>., and a snap whose name matches an enabled alias cannot be installed. image-tools is invented.
Now you install a second snap, image-tools, and the store gave it the alias convert too. Two snaps, one name. Who gets it? Snapd doesn't pick a winner on its own. The name is already enabled for photo editor, so the install stops and tells you so, with both snap names in the message. Manual aliases follow the same rule. There's a second rule as well. An alias can't be the name of an installed snap, or that name followed by a dot, because those names belong to the snap's own commands. So how do you choose?
06 snap prefer moves the name
snap install --unaliased installs with automatic aliases disabled. snap prefer <snap> enables that snap's aliases; in each conflicting snap it disables the automatic aliases and removes the manual ones. snap install --prefer combines both; the two flags cannot be used together.
You've got two ways out, and the careful one comes first: install image-tools with the --unaliased flag. It arrives with its automatic aliases known but off, so nothing collides. Then decide. snap prefer image-tools enables its aliases. To make room, it goes to every snap holding one of those names, and does more than you might expect: it disables that snap's automatic aliases and removes all its manual ones, your pconv included. The output lists each one. Installing with the --prefer flag does both steps in one go. And a second instance of photo editor arrives unaliased, unless you pass prefer.
07 Taking an alias away
snap unalias <alias> removes one manual alias. snap unalias <snap> disables all aliases of that snap, removing the manual ones; snap prefer <snap> re-enables the automatic ones.
Taking an alias away is one command with one argument, and it means two different things depending on what you hand it. Snapd first asks: is this word the name of an installed snap? If it isn't, snapd looks for a manual alias with that name and removes it. If it is, every alias of that snap is switched off. The automatic ones stay listed as disabled, and snap prefer turns them back on. The manual ones are gone, and you make them again with snap alias. The two meanings can't collide, because an alias can't be a snap's name.
08 Where to go from here
Roads: the snap-declaration, parallel installs, the overlord, packaging, snap-declaration rules, and apps and their environment.
Aliases are small, but they touch a few bigger things. The snap assertions deck shows the whole snap-declaration that carries automatic aliases. Parallel installs explains why a second instance arrives without its aliases. The overlord shows what a change is, and how a failed alias change is undone. Packaging shows where a snap's apps are declared. snap-declaration rules covers the other things the store decides for each snap. And apps and their environment covers completers.
Read more
Commands
| Command | Effect |
|---|---|
snap alias <snap.app> <alias> | set up a manual alias |
snap unalias <alias-or-snap> | remove one manual alias, or disable all aliases of a snap |
snap prefer <snap> | enable the snap's aliases, disabling conflicting aliases of other snaps |
snap aliases [<snap>] | list aliases: Command, Alias, Notes |
snap install --unaliased <snap> | install without enabling automatic aliases |
snap install --prefer <snap> | install, then prefer; one snap only |
alias, unalias and prefer need root or a logged-in snapd user; they name no polkit action, so no password dialog is offered.
alias, unalias and prefer accept --no-wait. They print Added: and Removed: followed by lines - <snap.app> as <alias>.
snap prefer does nothing when the snap's automatic aliases are already enabled. In each snap that holds a conflicting alias it removes all manual aliases and disables the automatic ones. It cannot resolve a conflict with a snap's own command names.
A new parallel instance of a snap, such as photo-editor_work, is installed as if --unaliased were given, unless --prefer is given. See Parallel installs.
Notes column
| Note | Meaning |
|---|---|
- | automatic alias, enabled |
manual | manual alias |
disabled | automatic alias, known but not enabled |
manual,override | manual alias with the name of an automatic alias; the manual target is used |
The published documentation calls automatic aliases "default aliases" and does not list override.
Messages
| Message | When |
|---|---|
cannot enable alias "A" for "S", already enabled for "T" | another snap holds the name |
cannot enable alias "A" for "S", it conflicts with the command namespace of installed snap "T" | the alias is T or begins with T. |
snap "S" command namespace conflicts with alias "A" for "T" snap | installing a snap whose name collides with an enabled alias |
cannot enable alias "A" for "S", target application "X" does not exist | snap alias on an unknown app |
cannot enable alias "A" for "S", target application "X" is a daemon | services cannot have aliases |
cannot find manual alias "A" in any snap | snap unalias on an unknown word |
cannot use unaliased and prefer flags together | both install flags given |
the prefer flag can only be specified on install | --prefer on another action |
No aliases are currently defined. | nothing to list |
for administrators for app developers
Changes and tasks
| Request | Change kind | Task kind | Task summary |
|---|---|---|---|
snap alias | alias | alias | Setup manual alias "A" => "X" for snap "S" |
snap unalias <alias> | unalias | unalias | Remove manual alias "A" for snap "S" |
snap unalias <snap> | unalias | disable-aliases | Disable aliases for snap "S" |
snap prefer | prefer | prefer-aliases | Prefer aliases for snap "S" |
| install, refresh | the snap's change | set-auto-aliases, setup-aliases | Set automatic aliases for snap "S", Setup snap "S" aliases |
install with --prefer | the snap's change | also prefer-aliases | |
| remove, disable | the snap's change | remove-aliases | Remove aliases for snap "S" |
| refresh after the declaration changed | the snap's change | refresh-aliases, prune-auto-aliases | for the snaps whose automatic aliases changed or were dropped |
Each alias command is a change with one task. The alias handlers share one undo and save the previous aliases on the task, so a failed or aborted change restores them. See The overlord.
for administrators for app developers
API
GET /v2/aliases: open to any local user. Returns snap, alias, thencommand,status(auto,manualordisabled),manualandauto.POST /v2/aliases: needs an authenticated user or root. Body:action(alias,unaliasorprefer),snap,app,alias.
for app developers
The snap-declaration header
aliases is a list of maps with name and target. A name must match ^[a-zA-Z0-9][-_.a-zA-Z0-9]*$. A duplicate is rejected with duplicated definition in "aliases" for alias "A". The older header auto-aliases is read when aliases is absent. How a publisher asks the store for an alias is a store process and is described in the second link below, not in the snapd source. See Assertions: snaps and validation.
Further reading
- Apps and aliases: the four commands and
--unaliasedwith sample output. - Process for aliases, auto-connections and tracks: how a publisher asks the store for an automatic alias.
- snap-declaration: the
aliasesheader. - Parallel installs: the section on application names and aliases of instances.
Roads from here
GETTING SNAPS
- Snap packaging — where the apps of a snap are declared
RUNNING SNAPS
- The overlord — alias commands are one-task changes with an undo
ASSERTIONS · signed statements snapd trusts
- Assertions: snaps and validation — the snap-declaration that carries automatic aliases
POLICY · who may install and connect what
- Snap-declaration rules — the other per-snap rules the store puts in a snap-declaration
ADMINISTRATION · managing a system of snaps
- Parallel installs — a second instance of a snap is installed without its automatic aliases
DEVELOPING SNAPS · try, pack, run, debug
- Apps, command lines and environment — completers and the other app keys