# atmos devcontainer shell

Use this command to quickly launch an interactive shell in a devcontainer. This is a convenience command equivalent to `start --attach` that provides the fastest way to get into a development environment.

## Usage

```shell
atmos devcontainer shell <name> [flags]
```

## Arguments

- **`name`** — Name of the devcontainer to launch (from `atmos.yaml` configuration)

## Flags

- **`--instance string`** — Instance name for this devcontainer (default: `default`). Use this to run multiple instances of the same devcontainer configuration.
- **`--identity string` or `-i`** — Authenticate with specified identity. Inside the container, cloud provider SDKs automatically use the authenticated identity.
- **`--new`** — Always create a new instance with auto-generated numbered name based on the `--instance` value (e.g., `default-1`, `default-2`, or `alice-1` with `--instance alice`). Use this when you want a fresh container that doesn't reuse existing instances.
- **`--replace`** — Destroy and recreate the instance specified by `--instance` flag. This rebuilds the container from scratch: if using a `build` configuration, it rebuilds the image from the Dockerfile; if using an `image`, it pulls the latest version. The container is then recreated with current configuration.
- **`--rm`** — Automatically remove the container when you exit the shell. Similar to Docker's `docker run --rm` behavior. Useful for temporary or one-off containers.
- **`--pty`** — Experimental: Use PTY mode with masking support (not available on Windows). Enables masking of sensitive values in terminal output. See [Secret Masking Configuration](/cli/configuration/settings/mask) for pattern configuration.

## Examples

### Basic Usage

```shell
# Launch shell in the geodesic devcontainer
atmos devcontainer shell geodesic

# Launch shell in a named instance
atmos devcontainer shell terraform --instance alice

# Launch shell with custom runtime (via environment variable)
export ATMOS_CONTAINER_RUNTIME=podman
atmos devcontainer shell geodesic
```

### Instance Management

```shell
# Create a new auto-numbered instance (default-1, default-2, etc.)
atmos devcontainer shell geodesic --new

# Create a new auto-numbered instance with custom base name
atmos devcontainer shell geodesic --instance alice --new
# Creates: alice-1, alice-2, etc.

# Rebuild existing instance from scratch
atmos devcontainer shell terraform --replace

# Rebuild a specific named instance
atmos devcontainer shell terraform --instance prod --replace
```

### Rebuilding Custom Dockerfiles

When using a devcontainer with a custom Dockerfile (using `build` configuration), the `--replace` flag will rebuild the image from your Dockerfile:

```shell
# After modifying your Dockerfile, rebuild and relaunch
atmos devcontainer shell geodesic --replace
```

This is particularly useful when:

- You've updated your Dockerfile with new tools or dependencies
- You want to pick up changes to build arguments
- You need a fresh container with the latest image build

### Temporary Containers

```shell
# Launch shell and auto-remove container on exit (like 'docker run --rm')
atmos devcontainer shell geodesic --rm

# Combine --new with --rm for completely ephemeral containers
atmos devcontainer shell geodesic --new --rm
```

### Authenticated Containers

```shell
# Launch shell with Atmos-managed identity
atmos devcontainer shell geodesic --identity prod-admin

# Launch new instance with identity that auto-removes on exit
atmos devcontainer shell terraform --identity dev-user --new --rm
```

## Behavior

This command performs the following operations automatically:

1. **Container doesn't exist**: Creates a new container with the configured image, mounts, ports, and environment variables
2. **Container exists but stopped**: Starts the existing container
3. **Container running**: Connects to the running container
4. **Always**: Attaches to the container with an interactive shell

The `shell` command is designed to be the quickest way to get into a devcontainer environment. It's equivalent to running `atmos devcontainer start <name> --attach` and follows the same pattern as other Atmos shell commands:

- `atmos terraform shell` - Interactive Terraform shell
- `atmos auth shell` - Interactive shell with authenticated identity

## Comparison with Other Commands

| Command | Creates Container | Starts Container | Attaches Shell |
|---------|------------------|------------------|----------------|
| `atmos devcontainer start` | ✅ | ✅ | ❌ |
| `atmos devcontainer start --attach` | ✅ | ✅ | ✅ |
| `atmos devcontainer shell` | ✅ | ✅ | ✅ |
| `atmos devcontainer attach` | ❌ | ❌ | ✅ |

**Use `shell` when**: You want to quickly get into an interactive development environment
**Use `start` when**: You want to start a container without attaching (e.g., to run background services)
**Use `attach` when**: The container is already running and you just want to connect to it

## Use with Aliases

The `shell` command works particularly well with command aliases in `atmos.yaml`:

```yaml
aliases:
  shell: "devcontainer shell geodesic"
```

This allows you to simply run:

```shell
atmos shell
```

This pattern provides a consistent experience with traditional shell wrappers like Geodesic.

## See Also

- [Devcontainer Configuration](/cli/configuration/devcontainer) — Configure devcontainers in `atmos.yaml`
- [`atmos devcontainer start`](/cli/commands/devcontainer/start)
- [`atmos devcontainer attach`](/cli/commands/devcontainer/attach)
- [`atmos devcontainer list`](/cli/commands/devcontainer/list)
- [Command Aliases](/cli/configuration/aliases)