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

80 lines
3.1 KiB
Markdown
Raw Normal View History

2023-07-04 06:18:46 +02:00
# Usage of the New CLI
2023-06-23 16:41:34 +02:00
2023-07-16 07:09:46 +02:00
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 [`nix develop` & `pkgs.mkShell`](/development/intro.md)
## `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:
2023-06-23 16:41:34 +02:00
```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.
2023-06-23 16:41:34 +02:00
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.
2023-06-23 16:41:34 +02:00
echo "Hello Nix" | nix run "github:NixOS/nixpkgs/nixos-unstable#ponysay"
```
## Common Use Cases for `nix run` and `nix shell`
2023-06-23 16:41:34 +02:00
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
2023-06-23 16:41:34 +02:00
```
Alternatively, you can use the following command:
```bash
nix shell nixpkgs#git
git clone git@github.com:ryan4yin/nix-config.git
```
2023-06-23 16:41:34 +02:00
[New Nix Commands]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html