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

# ubx shell

> Spawn an interactive shell or run a command with stack outputs as environment variables.

`ubx shell` spawns an interactive shell (or runs a specific command) with all stack outputs injected as environment variables, plus `UBX_ENV` and `UBX_STACK` meta-variables.

## Usage

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx shell [-- command [args...]] [flags]
```

## Flags

| Flag          | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| `--no-inject` | Skip output injection; only `UBX_ENV` and `UBX_STACK` are set |

## Examples

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx shell                               # spawn interactive $SHELL with outputs
ubx shell -- psql $DATABASE_URL         # run a command with outputs
ubx shell -- bash -c 'echo $VPC_ID'    # inline command
ubx shell --no-inject                   # shell without output injection
ubx shell --env prod                    # use prod stack outputs
```

## What gets injected

All non-secret stack outputs:

* Keys uppercased: `vpc_id` → `VPC_ID`
* Non-alphanumeric chars → `_`
* Secrets are **not** injected
* Objects/arrays become compact JSON strings

Plus meta-variables:

* `UBX_ENV` — current environment name
* `UBX_STACK` — current stack name

## Interactive shell

Without a command argument, `ubx shell` spawns `$SHELL` (or `/bin/sh` if `$SHELL` is not set):

```
  ◆ Shell       injecting 5 output(s) into environment
  ◆ Shell       spawning /bin/zsh

$ echo $VPC_ID
vpc-0a1b2c3d4e5f67890

$ exit
  ✓  shell exited
```

## Error handling

If stack outputs cannot be loaded (e.g. stack hasn't been deployed yet), ubx emits a warning and spawns the shell without injected output variables:

```
  Warning: could not load stack outputs (no .ubx/ dir) — spawning shell without injected vars
```

## Related commands

* [`ubx exec`](/v1/cli/exec) — non-interactive command runner (experimental)
* [`ubx output`](/v1/cli/output) — display outputs in various formats