> ## Documentation Index
> Fetch the complete documentation index at: https://flox.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# flox run

## NAME

flox-run - run a command from a Flox Catalog package

## SYNOPSIS

```text theme={null}
flox [<general-options>] run
     -p <package>
     -- <command> [<arguments>]
```

## DESCRIPTION

Run a command from a Flox Catalog package without creating an
environment.

`flox run` is designed for one-off invocations. It resolves the
requested package from the Flox Catalog, downloads its store paths, and
executes the command directly — no `flox init`, `flox install`, or
environment cleanup needed.

### Specifying the Package

The `-p`/`--package` flag is required and names the package explicitly.
For example:

```bash theme={null}
$ flox run -p gnugrep -- grep "pattern" file.txt
```

The package name is a plain Flox Catalog attribute path (e.g. `curl`,
`python3Packages.requests`).

### Flags Before and After the Command

`flox run` uses POSIX stop-at-first-positional parsing: flags before
`--` belong to `flox run`; everything after `--` is passed to the
command verbatim.

Always use `--` to separate the flox flags from the command:

```bash theme={null}
flox run -p curl -- curl http://example.com
```

Without `--`, flags that look like options could be claimed by the wrong
side of the boundary — for example,
`flox run -p curl curl -sL http://example.com` passes `-sL` to `curl`,
but `flox run curl -p curl -- curl ...` would fail because `-p` is
consumed by `curl`, leaving flox without a package.

**`--version` caveat:** Flox intercepts `--version` from the full
argument list before parsing. Always use `--` so `--version` reaches the
command:

```bash theme={null}
$ flox run -p hello -- hello --version   # ✅ shows hello's version
$ flox run -p hello hello --version      # ❌ shows flox's version instead
```

### Command Lookup

`flox run` looks up the command strictly inside the resolved package’s
output directories: `bin/` first, then `sbin/` (`bin/` wins if both
contain the command). The file must be a regular file with an executable
bit set.

There is no fallback to the caller’s `PATH`. If the command is not found
in the package, `flox run` exits with an error.

### Exec Semantics

`flox run` replaces the flox process with the invoked command via
`exec`. The caller’s PID becomes the command, signals go directly to it,
and the shell sees the command’s exit code. Stdin, stdout, and stderr
are inherited unmodified.

### Caching

Downloaded store paths are registered as GC roots under
`$FLOX_CACHE_DIR/run-gc-roots/`. Repeated invocations of the same
package skip the download step.

## OPTIONS

### Run Options

`-p <package>`, `--package <package>`\
Required. The Flox Catalog package that provides the command. Accepts
plain package names only (e.g. `curl`, `ripgrep`). Version constraints
(`@`), output selectors (`^`), and custom catalogs (`/`) are not
supported in this release.

`-- <command> [<arguments>]`\
The command to run and any arguments to pass to it. Use `--` to separate
flox flags from the command and its arguments.

### General Options

`-h`, `--help`\
Prints help information.

The following options can be passed when running any `flox` subcommand
but must be specified *before* the subcommand.

`-v`, `--verbose`\
Increase logging verbosity. Invoke multiple times for increasing detail.

`-q`, `--quiet`\
Silence logs except for errors.

## EXAMPLES

Run a command:

```bash theme={null}
$ flox run -p cowsay -- cowsay "Hello, Flox!"
```

Run a command whose name differs from the package name:

```bash theme={null}
$ flox run -p binutils -- readelf -a /bin/ls
```

Pass option-style arguments to the command:

```bash theme={null}
$ flox run -p curl -- curl -sL http://example.com
```

Pipe input to a command:

```bash theme={null}
$ echo '{"name":"Flox"}' | flox run -p jq -- jq '.name'
```

Show the command’s own help or version:

```bash theme={null}
$ flox run -p hello -- hello --help
$ flox run -p hello -- hello --version
```

## LIMITATIONS

This release (phase 1) requires the `-p`/`--package` flag. The following
features are not yet supported and will be available in a future
release:

* Defaulting the package to the command name (`flox run readelf`)
* Version constraints: `flox run -p curl@8.0 -- curl …`
* Output selectors: `flox run -p foo^dev …`
* Custom catalogs: `flox run -p mycatalog/vim -- vim …`
* Executable-to-package lookup and disambiguation

### Binary cache requirement

`flox run` fetches packages by store path using substitution only. It
does not evaluate Nix expressions or build packages from source unless
the binary cache does not have the package. A package must have a
pre-built binary available in the Nix binary cache, or be buildable from
source.

Packages that require building from source — including those with unfree
licenses that are not pre-cached — cannot be substituted directly.
`flox run` will build such packages from source automatically,
displaying a progress indicator while the build runs. Press Ctrl-C to
cancel if you do not want to wait. Built packages are stored in a
temporary GC root that is removed when the command exits. Use
`flox install` to add a package to a persistent environment instead.

## SEE ALSO

[`flox-activate`](/man/flox-activate),
[`flox-install`](/man/flox-install),
[`flox-search`](/man/flox-search)