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

# Docker Helpers

> Commands for managing development environments and executing commands within Docker containers.

Lager provides a suite of helper commands to create, manage, and interact with Docker-based development environments, as well as to execute commands directly within containers on the box.

## Development Environment (`devenv`)

The `devenv` command group helps you manage a consistent and reproducible development environment using Docker. It operates on a local `.lager.devenv` configuration file.

### `create`

Initializes a new development environment by creating a `.lager.devenv` configuration file in your current directory.

**Syntax**

```bash theme={null}
lager devenv create [OPTIONS]
```

**Options**

* `--image`: The Docker image to use. *(Default: `lagerdata/devenv-cortexm`)* -- You can use any Docker image suitable for your project.
* `--mount-dir`: The directory inside the container where your source code will be mounted. *(Default: `/app`)*
* `--shell`: The path to the shell executable within the Docker image. *(Default: `/bin/bash`)*

### `terminal`

Starts an interactive terminal session inside the development environment's Docker container. This is the primary way to "enter" your devenv.

**Syntax**

```bash theme={null}
lager devenv terminal [OPTIONS]
```

**Options**

* `-m`, `--mount`: Name of a volume to mount.
* `-u`, `--user`: The user to run as inside the container.
* `-g`, `--group`: The group to run as inside the container.
* `-n`, `--name`: Assign a name to the container.
* `-d`, `--detach`: Run the container in detached mode.
* `-p`, `--port`: Forward a port from the host to the container (e.g., `-p 8080:80`). Can be used multiple times.
* `--entrypoint`: Override the default entrypoint of the image.
* `--network`: The network mode for the container.
* `--platform`: The target platform if the image is multi-platform (e.g., `linux/amd64`).

### `add-command`

Adds a reusable command shortcut to your devenv configuration.

**Syntax**

```bash theme={null}
lager devenv add-command [OPTIONS] <COMMAND_NAME> [COMMAND]
```

**Arguments**

* `COMMAND_NAME`: The alias for your command (e.g., `build`).
* `COMMAND`: The shell command to execute (e.g., `"make clean && make"`). If not provided, you will be prompted.

**Options**

* `--warn` / `--no-warn`: Whether to print a warning if overwriting an existing command. *(Default: `--warn`)*

### `delete-command`

Removes a command shortcut from your devenv configuration.

**Syntax**

```bash theme={null}
lager devenv delete-command [OPTIONS] <COMMAND_NAME>
```

**Options**

* `--devenv <name>`: Delete the command from the devenv specified by `<name>`.

### `commands`

Lists all the custom command shortcuts saved in your devenv configuration.

**Syntax**

```bash theme={null}
lager devenv commands
```

### `delete`

Deletes the `.lager.devenv` configuration file from the current directory, effectively removing the development environment.

**Syntax**

```bash theme={null}
lager devenv delete [OPTIONS]
```

**Options**

* `--yes`: Confirm the action without prompting.

***

## Remote Execution (`exec`)

The `exec` command allows you to execute commands in a Docker container running on a remote Lager Box. This is useful for running tests or tasks that need to be close to the hardware.

### Syntax

```bash theme={null}
lager exec [OPTIONS] <COMMAND> [EXTRA_ARGS]
```

**Arguments**

* `COMMAND`: The named command alias to execute (previously saved with `--save-as`).
* `EXTRA_ARGS`: Additional arguments to be appended to the saved command.

**Options**

* `--command '<cmdline>'`: The raw command line to execute directly.
* `--save-as <alias>`: Saves the raw command specified with `--command` as a reusable alias.
* `--warn` / `--no-warn`: Whether to print a warning if overwriting an existing command. *(Default: `--warn`)*
* `--env FOO=BAR`: Set an environment variable for the command.
* `--passenv VAR`: Pass an environment variable from your current shell into the container.
* `-m`, `--mount`: Name of volume to mount.
* `-i`, `--interactive` / `--no-interactive`: Keep STDIN open even if not attached. *(Default: `--interactive`)*
* `-t`, `--tty` / `--no-tty`: Allocate a pseudo-TTY. *(Default: `--tty`)*
* `-u`, `--user`: User to run as in the container.
* `-g`, `--group`: Group to run as in the container.

### Examples

```bash theme={null}
# Execute a raw command on the Lager Box
lager exec --command 'ls -la /data' --box my-lager-box

# Save a command as an alias
lager exec --command 'pytest --verbose' --save-as my-tests --box my-lager-box

# Run the saved command
lager exec my-tests --box my-lager-box

# Run the saved command with extra arguments
lager exec my-tests -- --junit-xml=report.xml
```

## Notes

* COMMAND must be a named command previously saved using `--save-as`
* Use `--command` to execute raw commands directly
* `--save-as` creates reusable command aliases
* `--passenv` is useful for secrets, tokens, or passwords
* Volume mounts provide persistent storage access
* Interactive mode keeps STDIN open for user input
* TTY allocation provides proper terminal behavior
* User/group options control container execution context