olares-settings

# settings (Olares Settings UI mirror)

**CRITICAL — before doing anything, load the `olares-shared` skill first (profile selection, login, token refresh, auth-error recovery). Flag reference: `olares-cli settings --help`.**

> **Source of truth for flags is always `olares-cli settings <area> <verb> --help`.** This file only carries what `--help` cannot give: routing, the 13-section index, the role-caching / admin-vs-normal floor, the wire-format cheat sheet, and the common-errors table.

> **Platform model:** the Olares version/semver scheme behind `settings me version` is defined once in [`../olares-shared/references/olares-platform.md`](../olares-shared/references/olares-platform.md#olares-version--semver-model).

## When to use

- Olares Settings UI (https://docs.olares.com/manual/olares/settings/), olares-cli settings, role (owner / admin / normal), who am I on this Olares instance
- Areas: users, appearance, apps (entrances / env / domain / policy), integration (awss3 / tencent), VPN (devices / ACL / SSH), network, GPU, video, search, backup / restore, advanced (containerd registries, env)
- Mutating: language set, search rebuild, integration add/delete, VPN SSH / ACL, users create/delete

> Anything outside this scope -> see the **Skill suite map** in [`../olares-shared/SKILL.md`](../olares-shared/SKILL.md) (already loaded as the suite prerequisite).

> **Mental model:** `settings` covers configuration that the Olares Settings SPA exposes — **post-install per-app config**, mesh / VPN, backup, accounts, system appearance. Lifecycle and runtime live in sibling skills.

## 13 area sub-trees

The umbrella registers the 12 canonical Settings docs sections, plus a 13th non-canonical `me` self-service tree:

```
users         appearance   apps          integration   vpn         network
gpu           video        search        backup        restore     advanced
+ me (self-service: whoami / version / check-update / sso list)
```

Shape is always `olares-cli settings <area> <verb>` (or `<area> <noun> <verb>` when the area has multiple sub-resources, e.g. `vpn devices list`, `backup plans list`).

### Per-area `--help` and references

For every area, **start with `olares-cli settings <area> --help`**. References below cover the non-trivial sub-trees:

| Area | `--help` first, then... |
|---|---|
| `me` | `olares-cli settings me --help` (whoami / version / check-update / sso list) |
| `users` | [references/olares-settings-users.md](references/olares-settings-users.md) |
| `apps` | [references/olares-settings-apps.md](references/olares-settings-apps.md) (entrances / domain / policy / auth-level pipeline) |
| `vpn` | [references/olares-settings-vpn.md](references/olares-settings-vpn.md) (ACL deltas, SSH / subroutes / public-domain-policy) |
| `integration` | [references/olares-settings-integration.md](references/olares-settings-integration.md) (`accounts add awss3|tencent`) |
| `backup` | [references/olares-settings-backup.md](references/olares-settings-backup.md) (plans / snapshots / password) |
| `appearance` | `olares-cli settings appearance --help` (`get`, `language set`) |
| `network` | `olares-cli settings network --help` (read-only reverse-proxy / frp / hosts-file; writes blocked by JWS gap — see below) |
| `gpu` | `olares-cli settings gpu --help` (read-only `list`) |
| `video` | `olares-cli settings video --help` (read-only `config get`) |
| `search` | `olares-cli settings search --help` (`status`, `rebuild`, `dirs list`) |
| `restore` | `olares-cli settings restore --help` (read-only `plans list`) |
| `advanced` | `olares-cli settings advanced --help` (read-only `status`, `registries list`, `images list`, `env (system|user) list`) |

## Role caching + admin/normal floor

A profile carries the role its user has on the Olares instance — `owner`, `admin`, or `normal` — cached locally so the CLI can short-circuit gated verbs without a round-trip. Populated on `profile login` / `profile import`, refreshed by `olares-cli profile whoami --refresh`.

### Three whoami aliases, one driver

```bash
olares-cli profile whoami
olares-cli settings users me
olares-cli settings me whoami
```

All three delegate to the same driver — same output, same caching, same `--refresh`. **Never** suggest the user "should use the other one" — they are aliases on purpose.

### Floor table (admin-gated vs normal)

| Floor | Verbs |
|---|---|
| **Admin (owner / admin)** | `users list / get / create / delete`; `network reverse-proxy get`, `network frp list`, `network hosts-file get`; `gpu list`; `advanced status / registries list / images list`; `vpn ssh status/enable/disable`, `vpn subroutes status`, `vpn acl all/get/add/remove`, `vpn public-domain-policy get` |
| **Normal (any authenticated user)** | `me whoami / version / check-update / sso list`; `apps list/get`, `apps entrances list`, `apps env get`, `apps domain get`, `apps policy get`; `vpn devices list / routes <id>`; `appearance get`, `appearance language set`; `integration accounts list / list-by-type / get / add / delete`; `video config get`; `search status / dirs list / rebuild`; `backup plans list`, `backup snapshots list`; `restore plans list`; `advanced env (system|user) list` |

### Soft preflight behavior

- Admin-floor verbs check the cached role and fail fast with `role required: this command needs role "<R>" or higher to <verb>, but profile "<id>" is cached as "<r>"` **before any HTTP call**.
- Server-side 401 / 403 (e.g. role changed since last cache write) still gets the same refresh-and-retry hint, even on verbs that don't preflight.
- If role isn't cached yet, preflight is **soft**: it lets the call through and lets the server be authoritative.
- **The standard refresh path is `olares-cli profile whoami --refresh`** — recommend it whenever a settings verb returns a permission-shaped error.

## Output convention

Every read verb accepts `-o / --output {table,json}` (default `table`):

- `table` is tabwriter-formatted; columns differ per verb bu