# unikraft instances shell

The shell runs locally and the commands you type run on the instance.
Session state — the working directory, variables, functions, `$?` — is kept
here, while paths resolve against the instance, so `cd`, `*.log` and `> file`
all mean what you would expect.

A line starting with `:` is a builtin — `:get`, `:restart`, `:mount` and the
like; `:help` lists them.

The instance offers no terminal and no job control, so programs that need
one — `vim`, `top`, `less` — and `ctrl-z`, `bg` or `fg` will not work there yet.


```
unikraft instances shell <target> [flags]
```

## Examples

Open an interactive shell on a sandbox instance:

```bash
unikraft instance shell my-instance
```

Start the shell in a specific working directory:

```bash
unikraft instance shell my-instance --dir /var/lib/app
```

Run a single command line and exit:

```bash
unikraft instance shell my-instance -c 'cd /var/log && ls *.log'
```

## Options

```
  -c, --command line          Run a single command line and exit.
  -w, --dir dir               Directory to start the shell in. (default /)
  -e, --env <key>=<value>     Environment variable.
  --interrupt-grace duration  How long an interrupted command is given to report what it died of before the prompt comes back. (default 10s)
  --plugin name               Name of the sandbox plugin to use. (default sandbox)
  --reap-timeout duration     How long a command the shell stopped waiting for is given to finish in the background. (default 30s)
```

## Options inherited from parent commands

```
  --config file               Path to the configuration file.
  --log-level level           Set the logging level. (default info)
  --log-type type             Set the log type. (default text)
  --profile name              Set the current profile.
  --telemetry                 Toggle usage analytics. (default true)
  --timeout duration          Set a deadline for the command (e.g. 30s, 5m, 1h).
```

## See Also

* [`unikraft instances`](../instances.mdx): Manage Unikraft Cloud instances.