# `Docker.Command`
[🔗](https://github.com/joshrotenberg/docker_wrapper_ex/blob/v0.1.2/lib/docker/command.ex#L1)

Behaviour and runner for Docker commands.

Modules implementing this behaviour define how to build argument lists
for a specific Docker subcommand and how to parse the resulting output.

# `args`

```elixir
@callback args(command :: struct()) :: [String.t()]
```

Returns the argument list for this command.

# `parse_output`

```elixir
@callback parse_output(stdout :: String.t(), exit_code :: non_neg_integer()) ::
  {:ok, term()} | {:error, term()}
```

Parses the stdout and exit code from the Docker process into a result.

# `add_flag`

```elixir
@spec add_flag([String.t()], boolean(), String.t()) :: [String.t()]
```

Helper to add a flag to the arg list when a boolean is true.

# `add_opt`

```elixir
@spec add_opt([String.t()], term(), String.t()) :: [String.t()]
```

Helper to add an option with a value to the arg list when value is non-nil.

# `add_repeat`

```elixir
@spec add_repeat([String.t()], list(), (term() -> [String.t()])) :: [String.t()]
```

Helper to add repeated options from a list, applying a formatting function.

# `run`

```elixir
@spec run(module(), struct(), Docker.Config.t(), keyword()) ::
  {:ok, term()} | {:error, term()}
```

Runs a Docker command.

Takes a module implementing the `Docker.Command` behaviour, a command
struct, and a `Docker.Config`. Builds the full argument list, executes
Docker via `System.cmd/3`, and delegates parsing to the command module.

## Options

  * `:stream` - a function that receives each line of output as it's
    produced. When set, uses a Port for execution instead of `System.cmd`.
    The final result is still returned after the command completes.

Emits `:telemetry` events for observability:

  * `[:docker_wrapper, :command, :start]` -- before execution
  * `[:docker_wrapper, :command, :stop]` -- after execution

If the command exceeds the configured timeout, returns `{:error, :timeout}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*