# `SmolBox.Command`
[🔗](https://github.com/hfiguera/smolbox/blob/v0.1.3/lib/smolbox/command.ex#L1)

A bounded argument-vector command. No shell is inserted by SmolBox.

Timeouts are positive whole seconds, matching SmolVM's `timeoutSecs` field.
The initial maximum is five minutes; managed execution can impose an earlier
absolute deadline. `stdin` must be UTF-8 and SmolBox accepts it only for buffered
execution. Arbitrary binary data belongs in staged files.

# `t`

```elixir
@type t() :: %SmolBox.Command{
  argv: [String.t()],
  env: [{String.t(), String.t()}],
  stdin: String.t() | nil,
  timeout_secs: pos_integer(),
  user: String.t() | nil,
  workdir: String.t()
}
```

# `new`

```elixir
@spec new(term(), term()) :: {:ok, t()} | {:error, SmolBox.Error.t()}
```

Create a command from an executable and argument list, without inserting a shell.

`argv` has 1–256 UTF-8 entries, at most 16 KiB each and 64 KiB combined. The
executable must be nonempty; arguments may be empty. NUL bytes are rejected.

| Option | Default | Meaning |
|---|---|---|
| `:workdir` | `"/workspace"` | Validated absolute guest workspace path |
| `:timeout_secs` | `30` | Upstream command timeout, a whole number from 1–300 seconds |
| `:env` | `[]` | Up to 64 unique `{string_name, string_value}` pairs; names up to 128 bytes, values up to 8192 bytes |
| `:stdin` | `nil` | Up to 64 KiB of UTF-8 text; buffered execution only |
| `:user` | `nil` | Optional nonempty guest user string, at most 128 bytes |

Environment variable names use letters/digits/underscores and cannot begin
with a digit. Binary inputs belong in files. In managed execution, the command
timeout must fit the profile's `execution_ms` budget.

## Example

    iex> {:ok, command} = SmolBox.Command.new(["python", "/workspace/main.py"], timeout_secs: 10, env: [{"MODE", "demo"}])
    iex> {command.argv, command.timeout_secs, command.workdir}
    {["python", "/workspace/main.py"], 10, "/workspace"}

# `to_wire`

```elixir
@spec to_wire(t()) :: {:ok, map()} | {:error, SmolBox.Error.t()}
```

Return the exact camelCase request fields after validation.

# `validate`

```elixir
@spec validate(term()) :: :ok | {:error, SmolBox.Error.t()}
```

Revalidate a struct before transport, including manually constructed values.

---

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