# `Macaw.Auth.Native.UserCommands`
[🔗](https://github.com/dcoai/macaw_auth/blob/v0.4.1/lib/macaw/auth/native/user_commands.ex#L1)

The user commands of `mix macaw_auth.user` and of the release entry
points (`Macaw.Auth.Native.Release`), one implementation for both:

    list
    add NAME --role R [--role R…]
    disable NAME
    enable NAME
    password NAME
    roles NAME R…
    reset-second-factor NAME

and the release's `bootstrap NAME --role R` (`bootstrap/3`).

Each runs `Macaw.Auth.Native`'s own user functions and answers
`{:ok, objects}`, printed one JSON object per line, or
`{:error, message}`: a user's mistake is an answer, never a raise.

**A password never comes from the command line,** where `ps` and shell
history show it: `add`, `password` and `bootstrap` take it from an
environment variable, named by the caller (`:password_var`), and refuse
a `--password`, `--password=…` or `-p` among the arguments. No message
repeats an argument it didn't understand, which may be a password typed
in the wrong place; the only word a message repeats is a user's name.

# `bootstrap`

```elixir
@spec bootstrap([String.t()], String.t() | nil, keyword()) ::
  {:ok, [map()]} | {:error, String.t()}
```

`bootstrap NAME --role R`, the words after `bootstrap`: the first admin,
made by `Macaw.Auth.Native.bootstrap_admin/1` only when no user exists.
`{"ok": true, "created": NAME, "role": R}`, or, when any user exists,
`{"ok": true, "created": null, "reason": "a user already exists"}`.

# `run`

```elixir
@spec run([String.t()], String.t() | nil, keyword()) ::
  {:ok, [map()]} | {:error, String.t()}
```

Runs one user command: `argv` its words, `password` the value of the
password's environment variable (or nil). Options: `:password_var`,
the variable's name, for messages; `:announce`, passed to the functions
that revoke sessions (`false` in a process that is not the app's node).
The repo is started first when it isn't running (`start/0`).

# `start`

```elixir
@spec start() :: :ok | {:error, String.t()}
```

Makes ready what the commands need, in a process that has the app's
configuration but runs nothing of it (a mix task, a release's `eval`):
the native backend's configuration (`Macaw.Auth.Native.Config.fetch/0`;
a fault is `{:error, message}`) and its repo, started without query
logging, so nothing but the answer reaches stdout and no query's
parameters (a password's hash) reach a log. A running repo is used as it
is.

# `usage`

```elixir
@spec usage() :: String.t()
```

The commands' usage, as an error names it after `usage: `.

---

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