# 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)