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

▶ Watch this deck — 8 scenes, ~6 min

01 A shorter name for a long command

ALIASES every snap command is <snap>.<app>$ photo-editor.convert in.raw out.jpg $ sudo snap alias photo-editor.convert pconvAdded:- photo-editor.convert as pconv $ pconv in.raw out.jpgsame app, same confinementthe full name still works manual aliasyou set it with snap alias automatic aliaslisted by the store for this snapenabled at install the convert app of photo-editor is invented for this deck
A terminal runs photo-editor.convert, then snap alias photo-editor.convert pconv prints Added, and pconv runs the same app. Two boxes on the right: a manual alias, which you set with snap alias, and an automatic alias, which the store lists for the snap and snapd enables at install

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.

03 Reading snap aliases

WHAT IS SET $ snap aliasesCommand Alias Notes photo-editor.convert convert -automatic and enabled: a dash photo-editor.convert pconv manualmanual: you set it with snap alias $ sudo snap unalias photo-editor$ snap aliasesCommand Alias Notesphoto-editor.convert convert disabledconvert: known, switched offpconv: removed, a manual aliashas no off position automatic aliases are switched per snap: all of a snap's automatic aliases are on, or all are off manual,overrideyour alias has the name of an automatic one; yours is used
snap aliases prints Command, Alias and Notes. photo-editor.convert as convert has the note dash, an enabled automatic alias; as pconv it has the note manual. After snap unalias photo-editor, convert is disabled and pconv is gone. A manual alias with the name of an automatic one shows manual,override

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

WHERE THEY COME FROM photo-editorsnap.yamlaliasesnot declared here the storesnap-declaration, invented valuesaliases:-name: converttarget: convert snapdset-auto-aliasesat install and at every refresh;your manual aliases are kept target app missing: skippedtarget is a daemon: skipped no snap-id (a snap built and installed locally): no snap-declaration, no automatic aliases
The snap photo-editor cannot declare aliases in snap.yaml. The store puts an aliases list with name convert and target convert in the snap-declaration. snapd reads it in set-auto-aliases at install and at every refresh. Entries whose target app is missing or is a daemon are skipped. A snap with no snap-id has no automatic aliases

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

CONFLICTS photo-editorconvertenabled convertimage-toolsconvertinvented for this deck $ sudo snap install image-toolscannot enable alias "convert" for "image-tools",already enabled for "photo-editor"the install fails with this error $ sudo snap alias image-tools.convert photo-editor... it conflicts with the command namespace of installed snap "photo-editor"not a snap's name, nor <snap>. snap alias checks this while its change runs, so the refusal shows in the change: snap change --last=alias
photo-editor holds the alias convert. Installing image-tools, which also has the automatic alias convert, fails with cannot enable alias convert for image-tools, already enabled for photo-editor. A second rule: snap alias image-tools.convert photo-editor fails because it conflicts with the command namespace of an installed 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

CHOOSING photo-editorconvertimage-tools$ sudo snap install --unaliased image-toolsinstalled unaliased $ sudo snap prefer image-tools Added:- image-tools.convert as convert Removed:- photo-editor.convert as convert- photo-editor.convert as pconvautomatic off, manual removed in one go: sudo snap install --prefer image-tools--unaliased and --prefer cannot be combined a new instance such as photo-editor_work is installed unaliased unless you pass --preferprefer does nothing when the snap's aliases are on, and cannot resolve a clash with a snap's own commands
snap install --unaliased image-tools installs it with automatic aliases disabled. snap prefer image-tools prints Added image-tools.convert as convert and Removed photo-editor.convert as convert and as pconv. The alias convert moves from photo-editor to image-tools; photo-editor's manual aliases are removed and its automatic aliases disabled. snap install --prefer does both at once

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

UNALIAS snap unalias <word>is the word aninstalled snap? no$ sudo snap unalias pconvRemoved:- photo-editor.convert as pconvone manual alias is removed yes$ sudo snap unalias photo-editorRemoved:- photo-editor.convert as convert- photo-editor.convert as pconv $ sudo snap prefer photo-editorautomatic aliases: kept, disabledsnap prefer turns them back on manual aliases: gone;make them again with snap alias no clash between the two meanings: an alias cannot be the name of an installed snap
snap unalias takes one word. If the word is not an installed snap, snap unalias pconv removes one manual alias. If it is, snap unalias photo-editor removes the manual aliases and disables the automatic ones, and snap prefer photo-editor turns the automatic ones back on. A manual alias is made again with snap alias

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 AliasesAssertions: snaps and validationthe whole snap-declaration Parallel installsinstances arrive unaliased The overlordchanges and their undo Snap packagingwhere apps are declared Snap-declaration ruleswhat the store decides per snap Apps and environmentcompleters and other app keys
Roads from Aliases: snap assertions, parallel installs, the overlord, snap packaging, snap-declaration rules, and apps and their environment

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

CommandEffect
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

NoteMeaning
-automatic alias, enabled
manualmanual alias
disabledautomatic alias, known but not enabled
manual,overridemanual 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

MessageWhen
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" snapinstalling a snap whose name collides with an enabled alias
cannot enable alias "A" for "S", target application "X" does not existsnap alias on an unknown app
cannot enable alias "A" for "S", target application "X" is a daemonservices cannot have aliases
cannot find manual alias "A" in any snapsnap unalias on an unknown word
cannot use unaliased and prefer flags togetherboth 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

RequestChange kindTask kindTask summary
snap aliasaliasaliasSetup manual alias "A" => "X" for snap "S"
snap unalias <alias>unaliasunaliasRemove manual alias "A" for snap "S"
snap unalias <snap>unaliasdisable-aliasesDisable aliases for snap "S"
snap preferpreferprefer-aliasesPrefer aliases for snap "S"
install, refreshthe snap's changeset-auto-aliases, setup-aliasesSet automatic aliases for snap "S", Setup snap "S" aliases
install with --preferthe snap's changealso prefer-aliases
remove, disablethe snap's changeremove-aliasesRemove aliases for snap "S"
refresh after the declaration changedthe snap's changerefresh-aliases, prune-auto-aliasesfor 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, then command, status (auto, manual or disabled), manual and auto.
  • POST /v2/aliases: needs an authenticated user or root. Body: action (alias, unalias or prefer), 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

Roads from here

GETTING SNAPS

RUNNING SNAPS

  • The overlord — alias commands are one-task changes with an undo

ASSERTIONS · signed statements snapd trusts

POLICY · who may install and connect what

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