CLI experimental design

Allan Day edited this page Jan 12, 2018 · 27 revisions

An experimental design for what the flatpak CLI could look like. There's a page that has a small amount of background research.

Goals

  • Efficient information display
    • Effectively structure information, including use of white space
    • Avoid unnecessary visual noise
    • Prioritise the most important information
    • Don't show useless information
  • Be succinct, but also try to speak like a human
  • Follow standard English grammar and punctuation rules
  • Be consistent:
    • Consistent tone and terminology
    • Consistent layouts
    • Consistent information in output
  • Play it straight - avoid gimmicks, use neutral language, stick to the point
  • Anticipate errors and user intent. Be helpful.

Installing a single app

Details for the app are shown, along with install progress (labels should probably be in bold):

$ flatpak install flathub org.baedert.corebird
ID: org.baedert.corebird   Arch: x86_64   Version: stable   Download: 16.2 MB

Downloading...  [======================               ] 60%   5.1 MB/s  00:21

'Downloading...' changes to 'Installing...' when installing.

When installation is complete, the progress line is replaced by a status message and the command exits:

$ flatpak install flathub org.baedert.corebird
ID: org.baedert.corebird   Arch: x86_64   Version: stable   Download: 16.2 MB

Installation complete
$ █

Installing multiple items

List of things to be installed is presented, along with a confirmation step (column headings should be in bold):

$ flatpak install flathub org.baedert.corebird
ID                                Arch        Version      Remote       Download
org.gnome.Platform                x86_64      3.26         flathub      294.7 MB
org.gnome.Platform.Locale         x86_64      3.26         flathub      107.8 MB
org.gtk.Gtk3theme.Ambiance        x86_64      3.22         flathub        1.5 MB
org.baedert.corebird              x86_64      stable       flathub        7.3 MB
org.baedert.corebird.Locale       x86_64      stable       flathub       96.0 kB

Proceed with installation? [Y/n]: █

(It might not be necessary to show the remote here, since it's already in the command.)

Items in the list are ordered logically, so .Locale extensions follow the item they relate to.

Question defaults to Y, as indicated by the capitalisation. If proceed is selected, the confirmation is replaced by a line that shows progress. "Check marks" appear against each item, to indicate which ones have been installed. The box for the item that's being installed has a "spinner" next to it:

$ flatpak install flathub org.baedert.corebird
ID                                Arch        Version      Remote       Download
[+] org.gnome.Platform            x86_64      3.26         flathub      294.7 MB
[+] org.gnome.Platform.Locale     x86_64      3.26         flathub      107.8 MB
[/] org.gtk.Gtk3theme.Ambiance    x86_64      3.22         flathub        1.5 MB
[ ] org.baedert.corebird          x86_64      stable       flathub        7.3 MB
[ ] org.baedert.corebird.Locale   x86_64      stable       flathub       96.0 kB

Installing 3/5...   [=====                                ] 60%  5.1 MB/s  00:21

If a new remote was specified, the user is asked whether to permanently add it:

$ flatpak install org.baedert.corebird
ID                                Arch        Version      Remote       Download
[+] org.gnome.Platform            x86_64      3.26         flathub      294.7 MB
[+] org.gnome.Platform.Locale     x86_64      3.26         flathub      107.8 MB
[+] org.gtk.Gtk3theme.Ambiance    x86_64      3.22         flathub        1.5 MB
[+] org.baedert.corebird          x86_64      stable       flathub        7.3 MB
[+] org.baedert.corebird.Locale   x86_64      stable       flathub       96.0 kB

org.baedert.corebird installed

Permanently add remote 'flathub'? [Y/n]: █

If the answer is y, the confirmation prompt is replaced by a status message and the command exits:

$ flatpak install org.baedert.corebird
ID                                Arch        Version      Remote       Download
[+] org.gnome.Platform            x86_64      3.26         flathub      294.7 MB
[+] org.gnome.Platform.Locale     x86_64      3.26         flathub      107.8 MB
[+] org.gtk.Gtk3theme.Ambiance    x86_64      3.22         flathub        1.5 MB
[+] org.baedert.corebird          x86_64      stable       flathub        7.3 MB
[+] org.baedert.corebird.Locale   x86_64      stable       flathub       96.0 kB

org.baedert.corebird installed

Remote 'flathub' permanently added
$ █

An experimental design for what the flatpak CLI could look like.

Uninstalling a single app

$ flatpak uninstall org.baedert.corebird
ID: org.baedert.corebird   Arch: x86_64   Version: stable

/ Uninstalling...

The thing next to the status message is a spinner. If the operation is quick, this might When installation is complete, the progress line is replaced by a status message and the command exits:

$ flatpak uninstall org.baedert.corebird
ID: org.baedert.corebird   Arch: x86_64   Version: stable

Uninstall complete
$ █

Uninstalling multiple items

List of items is shown, with "check marks" next to them and a spinner for the item that is currently being uninstalled:

$ flatpak uninstall org.baedert.corebird
ID                                 Arch      Version
[-] org.gnome.Platform             x86_64    3.26
[-] org.gnome.Platform.Locale      x86_64    3.22
[/] org.gtk.Gtk3theme.Ambiance     x86_64    3.22
[ ] org.baedert.corebird           x86_64    stable
[ ] org.baedert.corebird.Locale    x86_64    stable

Uninstalling...
$ flatpak uninstall org.baedert.corebird
ID                                 Arch      Version
[-] org.gnome.Platform             x86_64    3.26
[-] org.gnome.Platform.Locale      x86_64    3.22
[-] org.gtk.Gtk3theme.Ambiance     x86_64    3.22
[-] org.baedert.corebird           x86_64    stable
[-] org.baedert.corebird.Locale    x86_64    stable

Uninstall complete
$ █

Search

search and info feature the user-facing app name and description, whereas other commands don't so much. This is because they are more exploratory and potentially useful for end-user cases.

Single result:

$ flatpak search corebird
Corebird - Native GTK Twitter client
ID: org.baedert.corebird   Arch: x86_64   Version: stable   Remote: flathub
$ █

Multiple results (column headers would be in bold):

$ flatpak search tux
Found in remote 'flathub'                                           ID                                     Arch     Version
Extreme Tux - High speed arctic racing game based on Tux Racer      Racernet.sourceforge.ExtremeTuxRacer   x86_64   stable
Tuxpaint -  A drawing program for children                          org.tuxpaint.Tuxpaint                  x86_64   stable
Tux Football - A great 2D soccer (sometimes called football) game   net.sourceforge.TuxFootball            x86_64   stable
$ █

Info

$ flatpak remote-info flathub org.gimp.GIMP
GIMP - Create images and edit photographs

       ID: org.gimp.GIMP
      Ref: app/org.gimp.GIMP/x86_64/stable
     Arch: x86_64
   Branch: stable
 Download: 47.2 MB
Installed: 127.2 MB
  Runtime: org.gnome.Platform/x86_64/3.24

   Commit: 7bda4b1cadf3d096f849e34f18c5934fa2e6dbe97b3269cabc2176e96e2a25fb
   Parent: 64a5dae3bfa8ef3a5c7b7a4e2f497f3e0d5c297c496710998d98846ac3fafcc8
  Subject: Build org.gimp.GIMP at 2f9a3362289727807db5b74d6ebf426d8a1f09a7
     Date: 2017-10-17 16:39:40 +0000
$ █

'Errors'

$ flatpak remote-info flathub org.gimp.gimp
Remote 'flathub' does not contain 'org.gimp.gimp'. Did you mean:
      org.gimp.GIMP
$ █
$ flatpak remote-indo flathub org.gimp.GIMP
'remote-indo' is not a flatpak command (see 'flatpak --help').

Did you mean:
      remote-info
$ █
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.