Skill: olares/olares-settings (version 4.0.1)

--- name: olares-settings version: 4.0.1 description: "Olares Settings (olares-cli settings) — read and mutate Olares Settings UI surfaces from the command line, scoped to the active Olares ID. Per-Olares-ID mirror of every section the Olares Settings SPA exposes (https://docs.olares.com/manual/olares/settings/). Read-only coverage: users, appearance, apps (list, get, entrances, env, domain, policy), integration accounts, VPN (devices, ACL, SSH, subroutes, public-domain policy), network (reverse proxy, frp, hosts file), GPU, video, search status + dirs, backup plans + snapshots, restore plans, advanced (containerd registries, images, env system / user), plus a `me` self-service tree (whoami on Olares, version, check-update, SSO list). Verified mutating verbs: appearance language set, search rebuild, integration accounts add awss3|tencent / delete, VPN SSH enable/disable, VPN ACL add/remove, users create/delete (new Olares ID). Use when the user mentions Olares, Olares ID, Olares Settings, olares-cli settings, the Olares Settings UI, role (owner / admin / normal) on Olares, integration accounts, SSO tokens, GPU mode, search index, backup / restore plans, containerd registries, VPN ACLs, language preference, or 'who am I on this Olares instance'." metadata: requires: bins: ["olares-cli"] cliHelp: "olares-cli settings --help" --- # settings (Olares Settings UI mirror) **CRITICAL — before doing anything, MUST use the Read tool to read [`../olares-shared/SKILL.md`](../olares-shared/SKILL.md) for profile selection, login, automatic token refresh, and the auth-error recovery table.** > **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. ## Routing | User intent | Use this skill? | |---|---| | "Change language / theme / appearance" | ✅ yes | | "Add a user / delete a user" | ✅ yes | | "Edit my app's entrance / domain / policy / env" | ✅ yes (post-install surface) | | "Add an S3 / Tencent integration account" | ✅ yes | | "Manage VPN devices / ACL / SSH toggle" | ✅ yes | | "Browse backup plans / snapshots / restore plans" | ✅ yes | | "Install / uninstall / upgrade / start / stop an Olares app" | ❌ use [`olares-market`](../olares-market/SKILL.md) (this is post-install) | | "Identify / log in / switch profile" | ❌ use [`../olares-shared/SKILL.md`](../olares-shared/SKILL.md) (`profile login`) | | "Inspect pods / workloads / nodes" | ❌ use [`olares-cluster`](../olares-cluster/SKILL.md) | | "Show CPU / memory / disk metrics" | ❌ use [`olares-dashboard`](../olares-dashboard/SKILL.md) | > **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 but always print a clear "no X" sentinel when the result set is empty. - `json` round-trips the upstream's already-unwrapped data verbatim. **Use `-o json` whenever the agent needs to feed the result into another tool** — column ordering, truncation, and human-friendly relabeling only happen in table mode. - A handful of verbs (`video config get`, `advanced status`) downgrade table output to a one-line summary because the upstream config is large; the hint to switch to JSON is printed inline. ## Wire-format cheat sheet Different upstream services return JSON in different envelopes. The CLI normalizes them per-area; this table is the cheat sheet for "what's the wire format for area X" when you need to fish out a non-tabled field via `-o json`: | Area | Endpoint family | Wire envelope | |---|---|---| | `me`, `apps`, `network`, `appearance`, `integration`, `gpu`, `video`, `search`, `advanced` | `/api/*` (user-service / BFL / terminusd) | Unwrapped BFL `{data: ...}` envelope | | `users` | `/api/users/v2`, `/api/users/:name`, `POST/DELETE /api/users/...` | List-result decoder; mutating returns axios-inner `{name}` | | `vpn` devices / ACL | `<SettingsURL>/headscale/machine`, `/headscale/machine/:id/routes` | Raw Headscale JSON (NO envelope), `route.id` is a string | | `vpn` public-domain-policy | [REDACTED_SECRET] | Already-unwrapped `{deny_all: 0|1}` | | `backup`, `restore` | `<SettingsURL>/apis/backup/v1/*` | BFL envelope; **different ingress prefix** (`/apis/backup/v1`, not `/api`) | | `video config get` | `/api/files/video/config` | BFL envelope, inner data as `json.RawMessage` (provider-versioned) | ## Currently-implemented mutating verbs Verbs marked **VERIFIED** have been confirmed against a live Olares instance. Verbs flagged **UNVERIFIED** ship in the binary but are tracked as experimental; the CLI emits a one-line "experimental" stderr hint when they run. | Area | Verb | Status | |---|---|---| | `appearance` | `language set <code>` | VERIFIED | | `users` | `create` / `delete` (with `--watch`) | VERIFIED | | `search` | `rebuild`, `dirs add / remove` | VERIFIED (rebuild + dirs writes) | | `vpn ssh` | `enable` / `disable` | VERIFIED | | `vpn acl` | `add` / `remove` | VERIFIED | | `integration accounts` | `add awss3` / `add tencent` / `delete` | VERIFIED | | `apps` | `suspend [--all]` / `resume`, `env set`, `domain set/finish`, `policy set`, `auth-level set` | UNVERIFIED | | `backup` | `password set` | UNVERIFIED | **Not yet implemented** (and the CLI deliberately does NOT register them): - App lifecycle (`install` / `uninstall` / `upgrade` / `start` / `stop` / `cancel` / `clone`) → use [`olares-market`](../olares-market/SKILL.md) instead - Per-app secrets / permissions / providers (Infisical-backed) → admin / chart-side tooling - Network writes requiring a JWS-signed device-id header (`hosts-file set`, `frp set`, `ssl enable/disable/update`) - Containerd registry mutations (`registries mirrors put/delete`, `images delete/prune`) — JWS-gated - Hardware / restart-class (reboot, shutdown, ssh-password, OS upgrade) — JWS-gated via TermiPass QR callback - Backup plan create / update (needs full `BackupPolicy` + `LocationConfig` vector design) - Restore plan update / non-cancel delete — backup-server has no routes **Don't suggest the deferred verbs today** — they will error with "command not found". ## Security rules - **Never** echo `<access_token>` or any field returned by `me sso list` into the terminal beyond what the table view shows. SSO tokens identify a TermiPass-bound device session and should never be logged or pasted into chat. - For writes that take secrets (`integration accounts add awss3|tencent`, future `backup password set`), **always read the secret from an env var or stdin pipe** — never paste it into chat or expand it inline in a suggested `olares-cli ...` command line. - `users create` / `users delete` are destructive. `delete` needs the whole word `yes` unless `--yes`. `delete` refuses owner accounts (rejected before DELETE). `create` always prints the initial password once to stdout — treat transcripts accordingly. - Read-only verbs do NOT carry "this will change X" prompts. **Don't fabricate one for read verbs.** - The `profile whoami --refresh` recovery path is the only authentication-adjacent action this skill recommends. **All** other auth recovery belongs in [`../olares-shared/SKILL.md`](../olares-shared/SKILL.md). ## Common errors → fixes | Error | Cause | Fix | |---|---|---| | `this command needs role "<R>" or higher to <verb>, but profile "<id>" is cached as "<r>"` | Cached role below the verb's floor | If your role on the server changed: `olares-cli profile whoami --refresh`. Otherwise ask owner to grant the role | | `HTTP 403 while attempting to <verb>` (with refresh hint) | Server rejected even though cache said OK — stale role cache | `olares-cli profile whoami --refresh`, retry the verb | | `refresh token for <id> became invalid at <ts>; please run: olares-cli profile login --olares-id <id>` | The refresh_token itself is dead — see [`../olares-shared/SKILL.md`](../olares-shared/SKILL.md) | `olares-cli profile login --olares-id <id>` | | `no access token for <id>; run: olares-cli profile login --olares-id <id>` | Keychain has no entry for the active profile | `olares-cli profile login` or `profile import` | | `unsupported --output "<x>" (allowed: table, json)` | Typo on `-o` | Use `-o table` or `-o json` | | `GET <path>: upstream returned code <N>: <msg>` | user-service / BFL / backup-server returned non-success envelope | Read the message verbatim; it almost always carries actionable detail (e.g. "user not found") | For the full auth-error matrix see [`../olares-shared/SKILL.md`](../olares-shared/SKILL.md).


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)