# `Alaja.Config`
[🔗](https://github.com/Lorenzo-SF/alaja/blob/2.1.0/lib/alaja/config.ex#L1)

Configuration management for Alaja CLI applications.

Values are read from `~/.config/alaja/alaja.conf` on first access and
kept in the Application environment for the lifetime of the process.
`set/2` writes through to both the in-memory store and the conf file.

In addition to the JSON config file, environment variables prefixed
with `ALAJAX_` override persisted values at load time. The mapping is
mechanical: `ALAJAX_COLOR_DEPTH` overrides `:color_depth`,
`ALAJAX_THEME_ACTIVE` overrides `:theme_active`. This lets CI shells
and one-off scripts override the on-disk config without rewriting it.

## Usage

    Alaja.Config.get(:color_depth, :truecolor)
    Alaja.Config.set(:color_depth, :xterm256)
    Alaja.Config.all()

# `all`

```elixir
@spec all() :: keyword()
```

Returns all configuration values (merged defaults + env + file).

# `config_file_path`

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

Returns the path to the config file.

# `get`

```elixir
@spec get(atom(), any()) :: any()
```

Gets a configuration value with fallback.

# `list_themes`

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

Returns available theme names.

# `load!`

```elixir
@spec load!(
  String.t(),
  keyword()
) :: :ok
```

Loads configuration from `path` and overlays `ALAJAX_*` env vars.

The on-disk JSON content is parsed into a map and each key is
written to Application env. Env vars win over the file content:
for every `{"ALAJAX_X" => :foo}` mapping, if the env var is set
and non-empty, its value (cast through `cast_env_value/2`) is
written last and therefore wins.

Pass `skip_env: true` to skip the env var overlay — useful in
tests that need deterministic, file-only behaviour regardless of
the BEAM-wide env state.

Missing files, malformed JSON, and parse errors are all swallowed
silently — Config must never crash an escript at startup. Returns
`:ok` once the overlay has been applied.

## Example

    iex> Alaja.Config.load!("/path/that/does/not/exist.json")
    :ok

# `load_theme`

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

Loads a theme by name.

# `lookup_theme_color`

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

Looks up a color key in the currently active theme.

This is the public API used by the Pote theme resolver bridge:
`"theme:<key>"` lookups in `Pote.Orchestrator` end up here when Alaja
is the running app, so e.g. `alaja separator --color "theme:ternary"`
resolves to the actual `ternary` color of the active theme, not Pote's
hardcoded default palette.

Returns `{:ok, {r, g, b}}` on hit, `:error` on miss (key absent or
theme file unreadable).

# `set`

```elixir
@spec set(atom(), any()) :: :ok
```

Sets a configuration value.

If the key is in the list of persistent keys it is also written to
`~/.config/alaja/alaja.conf`. Always updates the in-memory store.

---

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