nix command grouping mock

nix-ui-mock.md

The following is a suggestion for a grouping that I think might be useful. Obviously just a first sketch but personally I like it:

Usage: nix <COMMAND> <FLAGS>... <ARGS>...

Common flags:
      --debug                  enable debug output
      --help                   show usage information
      --help-config            show configuration options
      --no-net                 disable substituters and consider all previously downloaded files up-to-date
      --option <NAME> <VALUE>  set a Nix configuration option (overriding nix.conf)
  -L, --print-build-logs       print full build logs on stderr
      --quiet                  decrease verbosity level
      --refresh                consider all previously downloaded files out-of-date
  -v, --verbose                increase verbosity level
      --version                show version information

In addition, most configuration settings can be overriden using '--<name> <value>'.
Boolean settings can be overriden using '--<name>' or '--no-<name>'. See 'nix
--help-config' for a list of configuration settings.

The following are available commands for different scenarios:

building, running and evaluating

  app                       run a Nix application
  build                     build a derivation or fetch a store path
  dev-shell                 run a bash shell that provides the build environment of a derivation
  edit                      open the Nix expression of a Nix package in $EDITOR
  eval                      evaluate a Nix expression
  log                       show the build log of the specified packages or paths, if available
  print-dev-env             print shell code that can be sourced by bash to reproduce the build environment of a derivation
  repl                      start an interactive environment for evaluating Nix expressions
  run                       run a shell in which the specified packages are available
  search                    query available packages
  show-derivation           show the contents of a store derivation
  why-depends               show why a package has another package in its closure

operating on the Nix store

  add-to-store              add a path to the Nix store
  cat-store                 print the contents of a store file on stdout
  copy                      copy paths between Nix stores
  copy-sigs                 copy path signatures from substituters (like binary caches)
  ls-store                  show information about a store path
  make-content-addressable  rewrite a path or closure to content-addressable form
  optimise-store            replace identical files in the store by hard links
  path-info                 query information about store paths
  ping-store                test whether a store can be opened
  sign-paths                sign the specified paths
  verify                    verify the integrity of store paths

operating on NAR files

  cat-nar                   print the contents of a file inside a NAR file
  dump-path                 dump a store path to stdout (in NAR format)
  ls-nar                    show information about the contents of a NAR file

system commands

  doctor                    check your system for potential problems
  show-config               show the Nix configuration
  upgrade-nix               upgrade Nix to the latest stable version

working with hashes

  hash-file                 print cryptographic hash of a regular file
  hash-path                 print cryptographic hash of the NAR serialisation of a path
  to-base16                 convert a hash to base-16 representation
  to-base32                 convert a hash to base-32 representation
  to-base64                 convert a hash to base-64 representation
  to-sri                    convert a hash to SRI representation

working with flakes

  add                       upsert flake in user flake registry
  archive                   copy a flake and all its inputs to a store
  check                     check whether the flake evaluates and run its tests
  clone                     clone flake repository
  info                      list info about a given flake
  init                      create a skeleton 'flake.nix' file in the current directory
  list                      list available Nix flakes
  list-inputs               list flake inputs
  pin                       pin a flake to its current version in user flake registry
  remove                    remove flake from user flake registry
  show                      show the outputs provided by a flake
  update                    update flake lock file

Further down the road sub commands could be introduced - just like nix flakes meaning we would have:

• $ nix <app|build|dev-shell|edit|eval|log|print-dev-env|repl|run|search|show-derivation|why-depends>
• $ nix store <add|cat|copy|copy-sigs|ls|make-content-addressable|optimise|path-info|ping|sign-paths|verify>
• $ nix nar <cat|dump-path|ls>
• $ nix system <doctor|show-config|upgrade-nix>
• $ nix hash <file|path|to-base16|to-base32|to-base64|to-sri>
• $ nix flakes <add|archive|check|clone|info|init|list|list-inputs|pin|remove|show|update>

Note how in some instances prefixes are dropped because they would seem redundant:

$ nix ping-store
$ nix store ping-store
$ nix cat-nar
$ nix nar cat

Note that nix flake is already a subcommand, so it's nix flake add, not nix add. I agree it makes sense to put other commands under subcommands (e.g. nix hash to-base32).

In the nix --help output, it might be better to group commands by whether they're "porcelain" or "plumbing" (like the Git manpage). E.g. nix dev-shell is a main porcelain command, nix print-dev-env is plumbing (it's useful for other commands / scripts).

Yes your are right of course! I got carried away from just grouping things together.