.nh
.TH toolbox-run 1
.SH NAME
.PP
toolbox-run - Run a command in an existing toolbox container

.SH SYNOPSIS
.PP
\fBtoolbox run\fP [\fI--container NAME\fP | \fI-c NAME\fP]
            [\fI--distro DISTRO\fP | \fI-d DISTRO\fP]
            [\fI--preserve-fds N\fP]
            [\fI--release RELEASE\fP | \fI-r RELEASE\fP]
            [\fICOMMAND\fP]

.SH DESCRIPTION
.PP
Runs a command inside an existing toolbox container. The container should have
been created using the \fBtoolbox create\fR command.

.PP
On Fedora, the default container is known as \fBfedora-toolbox-N\fR, where N is
the release of the host. A specific container can be selected using the
\fB--container\fR option.

.PP
A toolbox container is an OCI container. Therefore, \fBtoolbox run\fR is analogous
to a \fBpodman start\fR followed by a \fBpodman exec\fR\&.

.SH OPTIONS
.PP
The following options are understood:

.PP
\fB--container\fP NAME, \fB-c\fP NAME

.PP
Run command inside a toolbox container with the given NAME. This is useful
when there are multiple toolbox containers created from the same image, or
entirely customized containers created from custom-built images.

.PP
\fB--distro\fP DISTRO, \fB-d\fP DISTRO

.PP
Run command inside a toolbox container for a different operating system DISTRO
than the host. Has to be coupled with \fB--release\fR unless the selected DISTRO
matches the host system.

.PP
\fB--preserve-fds\fP N

.PP
Pass down to command N additional file descriptors (in addition to 0, 1,
2). The total number of file descriptors will be 3+N.

.PP
\fB--release\fP RELEASE, \fB-r\fP RELEASE

.PP
Run command inside a toolbox container for a different operating system
RELEASE than the host.

.SH EXIT STATUS
.PP
The exit code gives information about why the command within the container
failed to run or why it exited.

.PP
\fB1\fP There was an internal error in Toolbox

.PP
\fB125\fP There was an internal error in Podman

.PP
\fB126\fP The run command could not be invoked

.EX
$ toolbox run /etc; echo $?
/bin/sh: line 1: /etc: Is a directory
/bin/sh: line 1: exec: /etc: cannot execute: Is a directory
Error: failed to invoke command /etc in container fedora-toolbox-36
126

.EE

.PP
\fB127\fP The run command cannot be found or the working directory does not exist

.EX
$ toolbox run foo; echo $?
/bin/sh: line 1: exec: foo: not found
Error: command foo not found in container fedora-toolbox-36
127

.EE

.PP
\fBExit code\fP The run command exit code

.EX
$ toolbox run false; echo $?
1

.EE

.SH EXAMPLES
.SS Run ls inside the default toolbox container matching the host OS
.EX
$ toolbox run ls -la

.EE

.SS Run emacs inside the default toolbox container for Fedora 36
.EX
$ toolbox run --distro fedora --release f36 emacs

.EE

.SS Run uptime inside a toolbox container with a custom name
.EX
$ toolbox run --container foo uptime

.EE

.SH SEE ALSO
.PP
\fBtoolbox(1)\fR, \fBpodman(1)\fR, \fBpodman-exec(1)\fR, \fBpodman-start(1)\fR