# CLI guideline

## Goals

Purpose of this document is to provide a clear direction to **help design
delightful command line** experience. This document contains guidelines to
follow to ensure a consistent and approachable user experience.

## Overview

`nix` command provides a single entry to a number of sub-commands that help
**developers and system administrators** in the life-cycle of a software
project. We particularly need to pay special attention to help and assist new
users of Nix.

# Naming the `COMMANDS`

Words matter. Naming is an important part of the usability. Users will be
interacting with Nix on a regular basis so we should **name things for ease of
understanding**.

We recommend following the [Principle of Least
Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment).
This means that you should **never use acronyms or abbreviations** unless they
are commonly used in other tools (e.g. `nix init`). And if the command name is
too long (> 10-12 characters) then shortening it makes sense (e.g.
“prioritization” → “priority”).

Commands should **follow a noun-verb dialogue**. Although noun-verb formatting
seems backwards from a speaking perspective (i.e. `nix store copy` vs. `nix
copy store`) it allows us to organize commands the same way users think about
completing an action (the group first, then the command).

## Naming rules

Rules are there to guide you by limiting your options. But not everything can
fit the rules all the time. In those cases document the exceptions in [Appendix
1: Commands naming exceptions](#appendix-1-commands-naming-exceptions) and
provide reason. The rules want to force a Nix developer to look, not just at
the command at hand, but also the command in a full context alongside other
`nix` commands.

```shell
$ nix [<GROUP>] <COMMAND> [<ARGUMENTS>] [<OPTIONS>]
```

- `GROUP`, `COMMAND`, `ARGUMENTS` and `OPTIONS` should be lowercase and in a
  singular form.
- `GROUP` should be a  **NOUN**.
- `COMMAND` should be a **VERB**.
- `ARGUMENTS` and `OPTIONS` are discussed in [*Input* section](#input).

## Classification

Some commands are more important, some less. While we want all of our commands
to be perfect we can only spend limited amount of time testing and improving
them.

This classification tries to separate commands in 3 categories in terms of
their importance in regards to the new users. Users who are likely to be
impacted the most by bad user experience.

- **Main commands**

  Commands used for our main use cases and most likely used by new users. We
  expect attention to details, such as:

    - Proper use of [colors](#colors), [emojis](#special-unicode-characters)
      and [aligning of text](#text-alignment).
    - [Autocomplete](#shell-completion) of options.
    - Show [next possible steps](#next-steps).
    - Showing some [“tips”](#educate-the-user) when running logs running tasks
      (eg. building / downloading) in order to teach users interesting bits of
      Nix ecosystem.
    - [Help pages](#help-is-essential) to be as good as we can write them
      pointing to external documentation and tutorials for more.

  Examples of such commands: `nix init`, `nix develop`, `nix build`, `nix run`,
  ...

- **Infrequently used commands**

  From infrequently used commands we expect less attention to details, but
  still some:

    - Proper use of [colors](#colors), [emojis](#special-unicode-characters)
      and [aligning of text](#text-alignment).
    - [Autocomplete](#shell-completion) of options.

  Examples of such commands: `nix edit`, `nix eval`, ...

- **Utility and scripting commands**

  Commands that expose certain internal functionality of `nix`, mostly used by
  other scripts.

    - [Autocomplete](#shell-completion) of options.

  Examples of such commands: `nix store copy`, `nix hash base16`, `nix store
  ping`, ...


# Help is essential

Help should be built into your command line so that new users can gradually
discover new features when they need them.