.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix3-run" "1" ""
.RS
.PP
\fBWarning\fR 
.br
This program is
\fB\fBexperimental\fR\fR
and its interface is subject to change.
.RE
.SH Name
.LP
\f(CRnix run\fR - run a Nix application
.SH Synopsis
.LP
\f(CRnix run\fR [\fIoption\fR\[u2026]] \fIinstallable\fR \fIargs\fR\[u2026]
.SH Examples
.IP "\(bu" 3
Run the default app from the \f(CRblender-bin\fR flake:
.LP
.EX
# nix run blender-bin
.EE
.IP "\(bu" 3
Run a non-default app from the \f(CRblender-bin\fR flake:
.LP
.EX
# nix run blender-bin#blender_2_83
.EE
.IP
Tip: you can find apps provided by this flake by running \f(CRnix flake
show blender-bin\fR.
.IP "\(bu" 3
Run \f(CRvim\fR from the \f(CRnixpkgs\fR flake:
.LP
.EX
# nix run nixpkgs#vim
.EE
.IP
Note that \f(CRvim\fR (as of the time of writing of this page) is not an
app but a package. Thus, Nix runs the eponymous file from the \f(CRvim\fR
package.
.IP "\(bu" 3
Run \f(CRvim\fR with arguments:
.LP
.EX
# nix run nixpkgs#vim -- --help
.EE
.SH Description
.LP
\f(CRnix run\fR builds and runs \fB\fIinstallable\fR\fR, which must evaluate to an
\fIapp\fR or a regular Nix derivation.
.PP
If \fIinstallable\fR evaluates to an \fIapp\fR (see below), it executes the
program specified by the app definition.
.PP
If \fIinstallable\fR evaluates to a derivation, it will try to execute the
program \f(CR<out>/bin/<name>\fR, where \fIout\fR is the primary output store
path of the derivation, and \fIname\fR is the first of the following that
exists:
.IP "\(bu" 3
The \f(CRmeta.mainProgram\fR attribute of the derivation.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
The \f(CRpname\fR attribute of the derivation.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 3
The name part of the value of the \f(CRname\fR attribute of the derivation.
.LP
For instance, if \f(CRname\fR is set to \f(CRhello-1.10\fR, \f(CRnix run\fR will run
\f(CR$out/bin/hello\fR.
.SH Flake output attributes
.LP
If no flake output attribute is given, \f(CRnix run\fR tries the following
flake output attributes:
.IP "\(bu" 3
\f(CRapps.<system>.default\fR
.IP "\(bu" 3
\f(CRpackages.<system>.default\fR
.LP
If an attribute \fIname\fR is given, \f(CRnix run\fR tries the following flake
output attributes:
.IP "\(bu" 3
\f(CRapps.<system>.<name>\fR
.IP "\(bu" 3
\f(CRpackages.<system>.<name>\fR
.IP "\(bu" 3
\f(CRlegacyPackages.<system>.<name>\fR
.SH Apps
.LP
An app is specified by a flake output attribute named
\f(CRapps.<system>.<name>\fR. It looks like this:
.LP
.EX
apps.x86_64-linux.blender_2_79 = {
  type = \(dqapp\(dq;
  program = \(dq${self.packages.x86_64-linux.blender_2_79}/bin/blender\(dq;
};
.EE
.PP
The only supported attributes are:
.IP "\(bu" 3
\f(CRtype\fR (required): Must be set to \f(CRapp\fR.
.IP "\(bu" 3
\f(CRprogram\fR (required): The full path of the executable to run. It
must reside in the Nix store.
.SH Options
.SS
Common evaluation options
.IP "\(bu" 3
\fB\f(CR--arg\fR\fR \fIname\fR \fIexpr\fR
.IP
Pass the value \fIexpr\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 3
\fB\f(CR--arg-from-file\fR\fR \fIname\fR \fIpath\fR
.IP
Pass the contents of file \fIpath\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 3
\fB\f(CR--arg-from-stdin\fR\fR \fIname\fR
.IP
Pass the contents of stdin as the argument \fIname\fR to Nix functions.
.IP "\(bu" 3
\fB\f(CR--argstr\fR\fR \fIname\fR \fIstring\fR
.IP
Pass the string \fIstring\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 3
\fB\f(CR--debugger\fR\fR
.IP
Start an interactive environment if evaluation fails.
.IP "\(bu" 3
\fB\f(CR--eval-store\fR\fR \fIstore-url\fR
.IP
The \fBURL of the Nix store\fR
to use for evaluation, i.e. to store derivations (\f(CR.drv\fR files) and inputs referenced by them.
.IP "\(bu" 3
\fB\f(CR--impure\fR\fR
.IP
Allow access to mutable paths and repositories.
.IP "\(bu" 3
\fB\f(CR--include\fR\fR / \f(CR-I\fR \fIpath\fR
.IP
Add \fIpath\fR to search path entries used to resolve \fBlookup paths\fR
.IP
This option may be given multiple times.
.IP
Paths added through \f(CR-I\fR take precedence over the \fB\f(CRnix-path\fR configuration setting\fR and the \fB\f(CRNIX_PATH\fR environment variable\fR.
.IP "\(bu" 3
\fB\f(CR--override-flake\fR\fR \fIoriginal-ref\fR \fIresolved-ref\fR
.IP
Override the flake registries, redirecting \fIoriginal-ref\fR to \fIresolved-ref\fR.
.SS
Common flake-related options
.IP "\(bu" 3
\fB\f(CR--commit-lock-file\fR\fR
.IP
Commit changes to the flake\(cqs lock file.
.IP "\(bu" 3
\fB\f(CR--inputs-from\fR\fR \fIflake-url\fR
.IP
Use the inputs of the specified flake as registry entries.
.IP "\(bu" 3
\fB\f(CR--no-registries\fR\fR
.IP
Don\(cqt allow lookups in the flake registries.
.RS
.IP
\fBDEPRECATED\fR
.IP
Use \fB\f(CR--no-use-registries\fR\fR instead.
.RE
.IP "\(bu" 3
\fB\f(CR--no-update-lock-file\fR\fR
.IP
Do not allow any updates to the flake\(cqs lock file.
.IP "\(bu" 3
\fB\f(CR--no-write-lock-file\fR\fR
.IP
Do not write the flake\(cqs newly generated lock file.
.IP "\(bu" 3
\fB\f(CR--output-lock-file\fR\fR \fIflake-lock-path\fR
.IP
Write the given lock file instead of \f(CRflake.lock\fR within the top-level flake.
.IP "\(bu" 3
\fB\f(CR--override-input\fR\fR \fIinput-path\fR \fIflake-url\fR
.IP
Override a specific flake input (e.g. \f(CRdwarffs/nixpkgs\fR). This implies \f(CR--no-write-lock-file\fR.
.IP "\(bu" 3
\fB\f(CR--recreate-lock-file\fR\fR
.IP
Recreate the flake\(cqs lock file from scratch.
.RS
.IP
\fBDEPRECATED\fR
.IP
Use \fB\f(CRnix flake update\fR\fR instead.
.RE
.IP "\(bu" 3
\fB\f(CR--reference-lock-file\fR\fR \fIflake-lock-path\fR
.IP
Read the given lock file instead of \f(CRflake.lock\fR within the top-level flake.
.IP "\(bu" 3
\fB\f(CR--update-input\fR\fR \fIinput-path\fR
.IP
Update a specific flake input (ignoring its previous entry in the lock file).
.RS
.IP
\fBDEPRECATED\fR
.IP
Use \fB\f(CRnix flake update\fR\fR instead.
.RE
.SS
Logging-related options
.IP "\(bu" 3
\fB\f(CR--debug\fR\fR
.IP
Set the logging verbosity level to \(oqdebug\(cq.
.IP "\(bu" 3
\fB\f(CR--log-format\fR\fR \fIformat\fR
.IP
Set the format of log output; one of \f(CRraw\fR, \f(CRinternal-json\fR, \f(CRbar\fR or \f(CRbar-with-logs\fR.
.IP "\(bu" 3
\fB\f(CR--print-build-logs\fR\fR / \f(CR-L\fR
.IP
Print full build logs on standard error.
.IP "\(bu" 3
\fB\f(CR--quiet\fR\fR
.IP
Decrease the logging verbosity level.
.IP "\(bu" 3
\fB\f(CR--verbose\fR\fR / \f(CR-v\fR
.IP
Increase the logging verbosity level.
.SS
Miscellaneous global options
.IP "\(bu" 3
\fB\f(CR--help\fR\fR
.IP
Show usage information.
.IP "\(bu" 3
\fB\f(CR--offline\fR\fR
.IP
Disable substituters and consider all previously downloaded files up-to-date.
.IP "\(bu" 3
\fB\f(CR--option\fR\fR \fIname\fR \fIvalue\fR
.IP
Set the Nix configuration setting \fIname\fR to \fIvalue\fR (overriding \f(CRnix.conf\fR).
.IP "\(bu" 3
\fB\f(CR--refresh\fR\fR
.IP
Consider all previously downloaded files out-of-date.
.IP "\(bu" 3
\fB\f(CR--repair\fR\fR
.IP
During evaluation, rewrite missing or corrupted files in the Nix store. During building, rebuild missing or corrupted store paths.
.IP "\(bu" 3
\fB\f(CR--version\fR\fR
.IP
Show version information.
.SS
Options that change the interpretation of \fBinstallables\fR
.IP "\(bu" 3
\fB\f(CR--expr\fR\fR \fIexpr\fR
.IP
Interpret \fB\fIinstallables\fR\fR as attribute paths relative to the Nix expression \fIexpr\fR.
.IP "\(bu" 3
\fB\f(CR--file\fR\fR / \f(CR-f\fR \fIfile\fR
.IP
Interpret \fB\fIinstallables\fR\fR as attribute paths relative to the Nix expression stored in \fIfile\fR. If \fIfile\fR is the character -, then a Nix expression will be read from standard input. Implies \f(CR--impure\fR.
.RS
.LP
\fBNote\fR
.PP
See \fB\f(CRman nix.conf\fR\fR for overriding configuration settings with command line flags.
.RE