nixos-and-flakes-book/docs/other-usage-of-flakes/the-new-cli.md

# Usage of the New CLI

Once you have enabled the `nix-command` and `flakes` features, you can start using the new generation Nix command-line tools provided by [New Nix Commands][New Nix Commands]. In this section, we will focus on two commands: `nix shell` and `nix run`. Other important commands like `nix build` will be discussed in detail in the chapter "Development Work on NixOS".

## `nix shell`

The `nix shell` command allows you to enter an environment with the specified Nix package and opens an interactive shell within that environment:

```shell
# hello is not available
› hello
hello: command not found

# Enter an environment with the 'hello' package
› nix shell nixpkgs#hello

# hello is now available
› hello
Hello, world!
```

## `nix run`

On the other hand, `nix run` creates an environment with the specified Nix package and directly runs that package within the environment (without installing it into the system environment):

```shell
# hello is not available
› hello
hello: command not found

# Create an environment with the 'hello' package and run it
› nix run nixpkgs#hello
Hello, world!
```

Since `nix run` directly executes the Nix package, the package specified as the argument must generate an executable program.

According to the `nix run --help` documentation, `nix run` executes the command `<out>/bin/<name>`, where `<out>` is the root directory of the derivation and `<name>` is selected in the following order:

- The `meta.mainProgram` attribute of the derivation
- The `pname` attribute of the derivation
- The content of the `name` attribute of the derivation with the version number removed

For example, in the case of the 'hello' package we tested earlier, `nix run` actually executes the program `$out/bin/hello`.

Here are two more examples with detailed explanations of the relevant parameters:

```bash
# Explanation of the command:
#   `nixpkgs#ponysay` means the 'ponysay' package in the 'nixpkgs' flake.
#   `nixpkgs` is a flake registry id, and Nix will find the corresponding GitHub repository address
#   from <https://github.com/NixOS/flake-registry/blob/master/flake-registry.json>.
# Therefore, this command creates a new environment, installs, and runs the 'ponysay' package provided by the 'nixpkgs' flake.
#   Note: It has been mentioned earlier that a Nix package is one of the outputs of a flake.
echo "Hello Nix" | nix run "nixpkgs#ponysay"

# This command has the same effect as the previous one, but it uses the complete flake URI instead of the flake registry id.
echo "Hello Nix" | nix run "github:NixOS/nixpkgs/nixos-unstable#ponysay"
```

## Common Use Cases for `nix run` and `nix shell`

These commands are commonly used for running temporary commands. For example, if I want to clone my configuration repository using Git on a new NixOS host without Git installed, I can use the following command:

```bash
nix run nixpkgs#git clone git@github.com:ryan4yin/nix-config.git
```

Alternatively, you can use the following command:

```bash
nix shell nixpkgs#git 
git clone git@github.com:ryan4yin/nix-config.git
```

[New Nix Commands]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html