# `CliSubprocessCore.Command`
[🔗](https://github.com/nshkrdotcom/cli_subprocess_core/blob/v0.1.0/lib/cli_subprocess_core/command.ex#L1)

Normalized subprocess invocation data shared by provider profiles.

The module also exposes the shared provider-aware one-shot command lane
through `run/1` and `run/2`.

# `env_key`

```elixir
@type env_key() :: String.t()
```

# `env_map`

```elixir
@type env_map() :: %{optional(env_key()) => env_value()}
```

# `env_value`

```elixir
@type env_value() :: String.t()
```

# `run_error`

```elixir
@type run_error() :: CliSubprocessCore.Command.Error.t()
```

# `run_result`

```elixir
@type run_result() :: CliSubprocessCore.Command.RunResult.t()
```

# `t`

```elixir
@type t() :: %CliSubprocessCore.Command{
  args: [String.t()],
  clear_env?: boolean(),
  command: String.t(),
  cwd: String.t() | nil,
  env: env_map(),
  user: user()
}
```

# `user`

```elixir
@type user() :: String.t() | nil
```

# `argv`

```elixir
@spec argv(t()) :: [String.t()]
```

Returns the executable and arguments as an argv list.

# `merge_env`

```elixir
@spec merge_env(t(), map()) :: t()
```

Merges environment variables into the invocation.

# `new`

```elixir
@spec new(
  String.t() | CliSubprocessCore.CommandSpec.t(),
  [String.t()] | keyword(),
  keyword()
) :: t()
```

Builds a normalized invocation struct.

# `put_env`

```elixir
@spec put_env(t(), String.t() | atom(), String.t() | atom() | number() | boolean()) ::
  t()
```

Adds or replaces a single environment variable.

# `run`

```elixir
@spec run(keyword()) :: {:ok, run_result()} | {:error, run_error()}
```

Runs a provider-aware one-shot command through the shared transport-owned
non-PTY lane.

Reserved command-lane options are:

- `:provider`
- `:profile`
- `:registry`
- `:stdin`
- `:timeout`
- `:stderr`
- `:close_stdin`

All remaining options are passed through to the resolved provider profile's
`build_invocation/1` callback.

# `run`

```elixir
@spec run(
  t(),
  keyword()
) :: {:ok, run_result()} | {:error, run_error()}
```

Runs a prebuilt normalized invocation through the shared non-PTY command
lane.

# `to_transport_command`

```elixir
@spec to_transport_command(t()) :: ExternalRuntimeTransport.Command.t()
```

Projects a CLI-domain invocation onto the generic transport substrate.

# `validate`

```elixir
@spec validate(t()) ::
  :ok
  | {:error, {:invalid_command, term()}}
  | {:error, {:invalid_args, term()}}
  | {:error, {:invalid_cwd, term()}}
  | {:error, {:invalid_env, term()}}
  | {:error, {:invalid_clear_env, term()}}
  | {:error, {:invalid_user, term()}}
```

Validates the invocation contract expected by the provider profile behaviour.

---

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