- [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.

## Looking for help

Since there is no standard way how user will look for help we rely on ways help
is provided by commonly used tools. As a guide for this we took `git` and
whenever in doubt look at it as a preferred direction.

The rules are:

- Help is shown by using `--help` or `help` command (eg `nix` `--``help` or
  `nix help`).
- For non-COMMANDs (eg. `nix` `--``help` and `nix store` `--``help`) we **show
  a summary** of most common use cases. Summary is presented on the STDOUT
  without any use of PAGER.
- For COMMANDs (eg. `nix init` `--``help` or `nix help init`) we display the
  man page of that command. By default the PAGER is used (as in `git`).
- At the end of either summary or man page there should be an URL pointing to
  an online version of more detailed documentation.
- The structure of summaries and man pages should be the same as in `git`.

## Anticipate where help is needed

Even better then requiring the user to search for help is to anticipate and
predict when user might need it. Either because the lack of discoverability,
typo in the input or simply taking the opportunity to teach the user of
interesting - but less visible - details.

### Shell completion

This type of help is most common and almost expected by users. We need to
**provide the best shell completion** for `bash`, `zsh` and `fish`.

Completion needs to be **context aware**, this mean when a user types:

```shell
$ nix build n<TAB>
```

we need to display a list of flakes starting with `n`.

### Wrong input

As we all know we humans make mistakes, all the time. When a typo - intentional
or unintentional - is made, we should prompt for closest possible options or
point to the documentation which would educate user to not make the same
errors. Here are few examples:

In first example we prompt the user for typing wrong command name:


```shell
$ nix int
------------------------------------------------------------------------
  Error! Command `int` not found.
------------------------------------------------------------------------
  Did you mean:
    |> nix init
    |> nix input
```

Sometimes users will make mistake either because of a typo or simply because of
lack of discoverability. Our handling of this cases needs to be context
sensitive.


```shell
$ nix init --template=template#python
------------------------------------------------------------------------
  Error! Template `template#python` not found.
------------------------------------------------------------------------
Initializing Nix project at `/path/to/here`.
      Select a template for you new project:
          |> template#python
             template#python-pip
             template#python-poetry
```

### Next steps

It can be invaluable to newcomers to show what a possible next steps and what
is the usual development workflow with Nix. For example:


```shell
$ nix init --template=template#python
Initializing project `template#python`
          in `/home/USER/dev/new-project`

  Next steps