Guix CLI, thoughts and suggestions

Guix CLI, thoughts and suggestions

[Ian Eure]

Greetings,

As I’ve been learning Guix, one of the things I’ve found somewhat 
unpleasant is the lack of consistency within the guix CLI tool. 
It feels a bit Git-like, with not much consistency, commands that 
non-obvioulsy perform more than operation, related commands in 
different places in the tree, etc.

Just so you know where I’m coming from: I’ve found that compliex 
CLI tooling benefits from organization and consistency.  The Linux 
ip(8) command is a good example of this kind of organization: to 
add an IP address, you use `ip address add'.  To show address, `ip 
address show', and to remove one `ip address del'.  When options 
are needed, they get added after the verb or branch in the verb 
tree; the final verb may take positional arguments as well as 
--long or -s (short)-form options.

Some examples of where I think Guix could do better.  This is an 
illustrative list, not an exhaustive one.

Inconsistent organization
=========================

Most package-related commands are under `guix package', but many 
are sibling commands.  Examples are `guix size', `guix lint', 
`guix hash', etc.


Inconsistency between verbs and options
=======================================

Some verbs are bare-word positional arguments, and others are 
flags to related verbs.  IMO, this is the biggest problem, and 
makes it very difficult to find all the things the CLI can do. 
`guix package' is a major offender in this area, as it mixes verbs 
and verb-specific options into the same level.  For example, 
installing a package is `guix package -i foo' rather than `guix 
package install foo', removing is `guix package -r foo' rather 
than `guix package remove foo', and listing installed packages is 
`guix package -I' rather than `guix package installed' (or 
similar).

This means that users can express commands which *seem* like they 
should work, but do not.  For example `guix package -i emacs -r 
emacs-pgtk -I' represents a command to 1) install emacs 2) remove 
emacs-pgtk 3) list installed packages (which would verify the 
previous two operations occurred).  This is a valid command within 
the accepted organization of `guix package', and doesn’t cause an 
error, but doesn’t work: the install and remove steps are ignored. 
A thing I’ve found throughout my career is that designing systems 
so it’s *impossible* to represent unsupported, nonsensical, or 
undefined things is an extremely valuable technique to avoid 
errors and pitfalls.  I think Guix could get a lot of mileage out 
of adopting something similar.

This causes a related problem of making it impossible to know what 
options are valid for what verbs.  Will `guix package --cores=8 -r 
emacs' remove the package while using eight cores of my system? 
Will `guix system -s i686 switch-generation 5' switch me to a 
32-bit version of generation 5?  If verbs are organized better, 
and have their own options, this ambiguity vanishes.


More inconsistency
==================

Other parts of guix have the opposite problem: `guix system 
docker-image' probably ought to be an option to `guix system 
image' rather than a separate verb.


Inconsistency between similar commands
======================================

There are generations of both the system (for GuixSD) and the user 
profile, however, they work differently.  For the system, there’s 
`guix system list-generations' and `guix system 
switch-generation', but for the user profile, you need `guix 
package --list-generations' and `guix package 
--switch-generation=PATTERN'.  Additionally, no help is available 
for either of the system commands: `guix system switch-generations 
--help' gives the same output as `guix system --help' -- no 
description of the supported ways of expressing a generation are 
available.


Flattened verbs
===============

Related, the generation-related commands under `guix system' ought 
to be one level deeper: `guix system generation list', `guix 
system generation switch' etc.


Repeated options
================

Many commands (`guix package', `guix system', `guix build', `guix 
shell') take -L options, to add Guile source to their load-path. 
This probably ought to be an option to guix itself, so you can do 
`guix -L~/src/my-channel build ...'.


Suggestions
===========

All commands should be organized into a tree of verbs.

Verbs should have common aliases (`rm' for `remove', etc).

Verbs should be selected by specifying the minimum unambiguous 
substring.  For example `guix sys gen sw' could refer to `guix 
system generation switch'.

Options should be applicable to each level of the tree, ex `guix 
-L~/src/my-channel' would add that load-path, which would be 
visible to any command.  

Requesting help is a verb.  Appending "help" to any level of the 
verb tree should show both options applicable to that verb, and 
its child verbs.  `guix help' would show global options and all 
top-level verbs (package, system, generation, etc); `guix package 
help' would show package-specific options and package-specific 
verbs; and so on.


Conclusion
==========

I have no idea if anyone feels similarly about this, or whether 
there’s appetite to change the CLI, but I think it’d be time 
well-spent.  Having some kind of agreed-upon standard for how the 
CLI stuff is organized seems like a good thing to me, even if it 
just stops or slows the addition of more commands with unique 
expressions.

It seems like a lot of work to change, and backwards compatibility 
also is an issue.  One option I could see working is shoving the 
entire existing structure under a command in the new tool, so you 
could do `guix old package -I' or similar.  An alternate approach 
would be using an environment variable to change behaviors.

What do you all think?

Thanks,

  — Ian

Re: Guix CLI, thoughts and suggestions

[Felix Lechner via Development of GNU Guix and the GNU System distribution.]

Hi Ian,

On Mon, Jan 15 2024, Ian Eure wrote:

> What do you all think?

The pain is not yet great enough to make changes.

Also, the interface may have more basic issues. [1]

Kind regards
Felix

[1] https://issues.guix.gnu.org/58908

Re: Guix CLI, thoughts and suggestions

[Carlo Zancanaro]

Hi Ian,

Much of what you've written is fair, and I'm sure that Guix's commands
could be better organised. I'm not really involved in Guix development,
but I think there are two "inconsistencies" that you've mentioned which
can be explained.

On Mon, Jan 15 2024, Ian Eure wrote:
> Some examples of where I think Guix could do better.  This is an
> illustrative list, not an exhaustive one.
>
> Inconsistent organization
> =========================
>
> Most package-related commands are under `guix package', but many are
> sibling commands.  Examples are `guix size', `guix lint', `guix hash',
> etc.

I think the real inconsistency here is that `guix package' is poorly
named. This command really operates on profiles, and performs operations
(install, remove, list, etc.) on those profiles. Packages are given as
arguments to this command.

The other commands operate on, and show the properties of, packages.
Similarly with `guix build'.

> Inconsistency between verbs and options
> =======================================

> ... For example, installing a package is `guix package -i foo' rather
> than `guix package install foo', removing is `guix package -r foo'
> rather than `guix package remove foo', and listing installed packages
> is `guix package -I' rather than `guix package installed' (or
> similar).

The specific example of `guix package' might be explained by considering
it as a single transaction to update the profile. The command `guix
package' really says "perform a transaction on the profile", and the
options are the commands in the transaction. Since there can be multiple
commands, and the command names look like package names, they are
provided as options.

This doesn't fully explain the behaviour. In particular the example you
give:

> This means that users can express commands which *seem* like they
> should work, but do not.  For example `guix package -i emacs -r
> emacs-pgtk -I' represents a command to 1) install emacs 2) remove
> emacs-pgtk 3) list installed packages (which would verify the previous
> two operations occurred). ...

seems reasonable to have working within the view of `guix package' as a
transactional operation.

It's also worth noting that there are convenience shortcuts in `guix
install' and `guix remove'.

> It seems like a lot of work to change, and backwards compatibility
> also is an issue.

I see backwards compatibility as the main issue here. There was a lot of
discussion preceding the inclusion of `guix shell', because of the
prospect of breaking existing tutorials/documentation floating around on
the internet. This is an even bigger concern for a more drastic
reorganisation of the CLI.

Carlo

Re: Guix CLI, thoughts and suggestions

[Efraim Flashner]

[-- Attachment #1: Type: text/plain, Size: 6933 bytes --]

On Mon, Jan 15, 2024 at 11:24:29AM -0800, Ian Eure wrote:
> Greetings,
> 
> As I’ve been learning Guix, one of the things I’ve found somewhat unpleasant
> is the lack of consistency within the guix CLI tool. It feels a bit
> Git-like, with not much consistency, commands that non-obvioulsy perform
> more than operation, related commands in different places in the tree, etc.
> 
> Just so you know where I’m coming from: I’ve found that compliex CLI tooling
> benefits from organization and consistency.  The Linux ip(8) command is a
> good example of this kind of organization: to add an IP address, you use `ip
> address add'.  To show address, `ip address show', and to remove one `ip
> address del'.  When options are needed, they get added after the verb or
> branch in the verb tree; the final verb may take positional arguments as
> well as --long or -s (short)-form options.
> 
> Some examples of where I think Guix could do better.  This is an
> illustrative list, not an exhaustive one.
> 
> Inconsistent organization
> =========================
> 
> Most package-related commands are under `guix package', but many are sibling
> commands.  Examples are `guix size', `guix lint', `guix hash', etc.
> 
> 
> Inconsistency between verbs and options
> =======================================
> 
> Some verbs are bare-word positional arguments, and others are flags to
> related verbs.  IMO, this is the biggest problem, and makes it very
> difficult to find all the things the CLI can do. `guix package' is a major
> offender in this area, as it mixes verbs and verb-specific options into the
> same level.  For example, installing a package is `guix package -i foo'
> rather than `guix package install foo', removing is `guix package -r foo'
> rather than `guix package remove foo', and listing installed packages is
> `guix package -I' rather than `guix package installed' (or similar).
> 
> This means that users can express commands which *seem* like they should
> work, but do not.  For example `guix package -i emacs -r emacs-pgtk -I'
> represents a command to 1) install emacs 2) remove emacs-pgtk 3) list
> installed packages (which would verify the previous two operations
> occurred).  This is a valid command within the accepted organization of
> `guix package', and doesn’t cause an error, but doesn’t work: the install
> and remove steps are ignored.

I found this part surprising. I know you can chain together -i and -r,
but I had never tried adding -I to the list also, and it makes sense to
me that it should be able to be chained in also.

>                               A thing I’ve found throughout my career is
> that designing systems so it’s *impossible* to represent unsupported,
> nonsensical, or undefined things is an extremely valuable technique to avoid
> errors and pitfalls.  I think Guix could get a lot of mileage out of
> adopting something similar.
> 
> This causes a related problem of making it impossible to know what options
> are valid for what verbs.  Will `guix package --cores=8 -r emacs' remove the
> package while using eight cores of my system? Will `guix system -s i686
> switch-generation 5' switch me to a 32-bit version of generation 5?  If
> verbs are organized better, and have their own options, this ambiguity
> vanishes.
> 
> 
> More inconsistency
> ==================
> 
> Other parts of guix have the opposite problem: `guix system docker-image'
> probably ought to be an option to `guix system image' rather than a separate
> verb.
> 
> 
> Inconsistency between similar commands
> ======================================
> 
> There are generations of both the system (for GuixSD) and the user profile,
> however, they work differently.  For the system, there’s `guix system
> list-generations' and `guix system switch-generation', but for the user
> profile, you need `guix package --list-generations' and `guix package
> --switch-generation=PATTERN'.  Additionally, no help is available for either
> of the system commands: `guix system switch-generations --help' gives the
> same output as `guix system --help' -- no description of the supported ways
> of expressing a generation are available.
> 
> 
> Flattened verbs
> ===============
> 
> Related, the generation-related commands under `guix system' ought to be one
> level deeper: `guix system generation list', `guix system generation switch'
> etc.
> 
> 
> Repeated options
> ================
> 
> Many commands (`guix package', `guix system', `guix build', `guix shell')
> take -L options, to add Guile source to their load-path. This probably ought
> to be an option to guix itself, so you can do `guix -L~/src/my-channel build
> ...'.
> 
> 
> Suggestions
> ===========
> 
> All commands should be organized into a tree of verbs.
> 
> Verbs should have common aliases (`rm' for `remove', etc).
> 
> Verbs should be selected by specifying the minimum unambiguous substring.
> For example `guix sys gen sw' could refer to `guix system generation
> switch'.
> 
> Options should be applicable to each level of the tree, ex `guix
> -L~/src/my-channel' would add that load-path, which would be visible to any
> command.
> 
> Requesting help is a verb.  Appending "help" to any level of the verb tree
> should show both options applicable to that verb, and its child verbs.
> `guix help' would show global options and all top-level verbs (package,
> system, generation, etc); `guix package help' would show package-specific
> options and package-specific verbs; and so on.
> 
> 
> Conclusion
> ==========
> 
> I have no idea if anyone feels similarly about this, or whether there’s
> appetite to change the CLI, but I think it’d be time well-spent.  Having
> some kind of agreed-upon standard for how the CLI stuff is organized seems
> like a good thing to me, even if it just stops or slows the addition of more
> commands with unique expressions.
> 
> It seems like a lot of work to change, and backwards compatibility also is
> an issue.  One option I could see working is shoving the entire existing
> structure under a command in the new tool, so you could do `guix old package
> -I' or similar.  An alternate approach would be using an environment
> variable to change behaviors.
> 
> What do you all think?

This is probably the most well written critique I've seen on the layout
of the CLI for Guix.

I think it would be worthwhile to mock-up a 'guix profile' command to
see how it would look. I'm going to add it as a possible topic for Guix
Days just before FOSDEM and see if we can create something that makes
more sense.

-- 
Efraim Flashner   <efraim@flashner.co.il>   רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Guix CLI, thoughts and suggestions

[Rostislav Svoboda]

I find the discrepancy regarding two dashes '--' is annoying:

$ guix package --list-generations=1d
...
$ guix describe --list-generations=1d
guix system: error: list-generations=1d: unrecognized option
$ guix describe list-generations=1d
...

And more importantly, I'd be happy if the CLI and REPL syntax were
united, so that there's minimal difference between a shell command
call and a Guile function call. E.g. following would do the same:

$ guix :show emacs
scheme@(guix-user)> (guix :show emacs)


This would greatly facilitate the shell-to-Guile script conversion.

(This way, for comp-sci newcomers, it's much easier to see what a
(bash) shell, with its quirky DSL, really is - not an interface making
computers easier to use, but a barrier obstructing you from properly
using computers as programmable stateful machines. See
https://www.gnu.org/software/guile/manual/html_node/Prompts.html )

Unfortunately, the '#' indicates a comment-start in shells and, as
AFAICS in the source code, we prefer the #:keyword syntax over
:keyword. (Here, in the first step, on an experimental branch, we
could try to add (read-set! keywords 'prefix) everywhere, just to see
what breaks ;-)

Cheers Bost

Re: Guix CLI, thoughts and suggestions

[Ian Eure]

Hi Carlo,

Thank you for the thoughtful reply.

Carlo Zancanaro <carlo@zancanaro.id.au> writes:

> Hi Ian,
>
> Much of what you've written is fair, and I'm sure that Guix's 
> commands
> could be better organised. I'm not really involved in Guix 
> development,
> but I think there are two "inconsistencies" that you've 
> mentioned which
> can be explained.
>
> On Mon, Jan 15 2024, Ian Eure wrote:
>> Some examples of where I think Guix could do better.  This is 
>> an
>> illustrative list, not an exhaustive one.
>>
>> Inconsistent organization
>> =========================
>>
>> Most package-related commands are under `guix package', but 
>> many are
>> sibling commands.  Examples are `guix size', `guix lint', `guix 
>> hash',
>> etc.
>
> I think the real inconsistency here is that `guix package' is 
> poorly
> named. This command really operates on profiles, and performs 
> operations
> (install, remove, list, etc.) on those profiles. Packages are 
> given as
> arguments to this command.
>
> The other commands operate on, and show the properties of, 
> packages.
> Similarly with `guix build'.
>

Yes, I agree the behavior makes a bit more sense from that 
viewpoint.  However, it does have non-profile-related things in 
it, such as `--show' and `--search'.  This is getitng into another 
thing I’ve seen a bit of, which is overloaded commands -- ones 
that do multiple things that are unrelated or tangentally related. 
But, I didn’t have a good example, and my message was long enough 
already.



>> Inconsistency between verbs and options
>> =======================================
>
>> ... For example, installing a package is `guix package -i foo' 
>> rather
>> than `guix package install foo', removing is `guix package -r 
>> foo'
>> rather than `guix package remove foo', and listing installed 
>> packages
>> is `guix package -I' rather than `guix package installed' (or
>> similar).
>
> The specific example of `guix package' might be explained by 
> considering
> it as a single transaction to update the profile. The command 
> `guix
> package' really says "perform a transaction on the profile", and 
> the
> options are the commands in the transaction. Since there can be 
> multiple
> commands, and the command names look like package names, they 
> are
> provided as options.
>
> This doesn't fully explain the behaviour. In particular the 
> example you
> give:
>
>> This means that users can express commands which *seem* like 
>> they
>> should work, but do not.  For example `guix package -i emacs -r
>> emacs-pgtk -I' represents a command to 1) install emacs 2) 
>> remove
>> emacs-pgtk 3) list installed packages (which would verify the 
>> previous
>> two operations occurred). ...
>
> seems reasonable to have working within the view of `guix 
> package' as a
> transactional operation.
>

I agree that this would make sense, but my understanding is that 
`guix package' doesn’t work like that -- it only performs the 
final operation in the list.  IMO, it should either do 
*everything* the commands specify, or print an error and take no 
action.


> It's also worth noting that there are convenience shortcuts in 
> `guix
> install' and `guix remove'.
>
>> It seems like a lot of work to change, and backwards 
>> compatibility
>> also is an issue.
>
> I see backwards compatibility as the main issue here. There was 
> a lot of
> discussion preceding the inclusion of `guix shell', because of 
> the
> prospect of breaking existing tutorials/documentation floating 
> around on
> the internet. This is an even bigger concern for a more drastic
> reorganisation of the CLI.
>

I agree, I don’t think the situation can be improved without 
finding a solution to preserve BC.  But, I didn’t think it was 
worth making detailed plans for any of this before gauging whether 
the problem was one broadly considered to be worth solving.

  — Ian

Re: Guix CLI, thoughts and suggestions

[Carlo Zancanaro]

Hi Ian,

On Sat, Jan 20 2024, Ian Eure wrote:
> I agree that this would make sense, but my understanding is that `guix
> package' doesn’t work like that -- it only performs the final
> operation in the list.  IMO, it should either do *everything* the
> commands specify, or print an error and take no action.

It can accumulate multiple commands. As an example, if you create a
profile with a single package in it:

  $ guix package -i hello
  The following package will be installed:
     hello 2.12.1
  ... more output...

then you can remove that package and install another package in a single
transaction:

  $ guix package -r hello -i coreutils
  The following package will be removed:
     hello 2.12.1

  The following package will be installed:
     coreutils 9.1
  ... more output...

The inconsistency here is that some commands can be combined
(specifically adding and removing), whereas others cannot (probably
everything else).

> I agree, I don’t think the situation can be improved without finding a
> solution to preserve BC.  But, I didn’t think it was worth making
> detailed plans for any of this before gauging whether the problem was
> one broadly considered to be worth solving.

I think it would be great to have a consistent CLI, so I would love it
if we were able to solve this problem.

Carlo

Re: Guix CLI, thoughts and suggestions

[Rostislav Svoboda]

This is something we're capable of too, right?
https://everything.curl.dev/libcurl/libcurl

Bost

Le lun. 22 janv. 2024 à 01:22, Carlo Zancanaro <carlo@zancanaro.id.au> a écrit :
>
> Hi Ian,
>
> On Sat, Jan 20 2024, Ian Eure wrote:
> > I agree that this would make sense, but my understanding is that `guix
> > package' doesn’t work like that -- it only performs the final
> > operation in the list.  IMO, it should either do *everything* the
> > commands specify, or print an error and take no action.
>
> It can accumulate multiple commands. As an example, if you create a
> profile with a single package in it:
>
>   $ guix package -i hello
>   The following package will be installed:
>      hello 2.12.1
>   ... more output...
>
> then you can remove that package and install another package in a single
> transaction:
>
>   $ guix package -r hello -i coreutils
>   The following package will be removed:
>      hello 2.12.1
>
>   The following package will be installed:
>      coreutils 9.1
>   ... more output...
>
> The inconsistency here is that some commands can be combined
> (specifically adding and removing), whereas others cannot (probably
> everything else).
>
> > I agree, I don’t think the situation can be improved without finding a
> > solution to preserve BC.  But, I didn’t think it was worth making
> > detailed plans for any of this before gauging whether the problem was
> > one broadly considered to be worth solving.
>
> I think it would be great to have a consistent CLI, so I would love it
> if we were able to solve this problem.
>
> Carlo
>