.TH "BST SHELL" "1" "2020-04-23" "" "bst shell Manual"
.SH NAME
bst\-shell \- Shell into an element's sandbox environment
.SH SYNOPSIS
.B bst shell
[OPTIONS] [ELEMENT] [COMMAND]...
.SH DESCRIPTION
Run a command in the target element's sandbox environment
.PP
When this command is executed from a workspace directory, the default
is to shell into the workspace element.
.PP
This will stage a temporary sysroot for running the target
element, assuming it has already been built and all required
artifacts are in the local cache.
.PP
Use '--' to separate a command from the options to bst,
otherwise bst may respond to them instead. e.g.
.PP

    bst shell example.bst -- df -h
.PP
Use the --build option to create a temporary sysroot for
building the element instead.
.PP
Use the --sysroot option with an existing failed build
directory or with a checkout of the given target, in order
to use a specific sysroot.
.PP
If no COMMAND is specified, the default is to attempt
to run an interactive shell.
.SH OPTIONS
.TP
\fB\-b,\fP \-\-build
Stage dependencies and sources to build
.TP
\fB\-s,\fP \-\-sysroot DIRECTORY
An existing sysroot
.TP
\fB\-\-mount\fP HOSTPATH PATH
Mount a file or directory into the sandbox
.TP
\fB\-\-isolate\fP
Create an isolated build sandbox
.TP
\fB\-t,\fP \-\-use\-buildtree [ask|try|always|never]
Stage a buildtree. If `always` is set, will always fail to build if a buildtree is not available. --pull and pull-buildtrees configuration is needed if trying to query for remotely cached buildtrees.  [default: ask]
.TP
\fB\-\-pull\fP
Attempt to pull missing or incomplete artifacts