| name | olares-settings |
| version | 4.4.2 |
| description | Olares Settings via olares-cli settings — mirror of Settings SPA: users, apps, VPN, network (reverse-proxy / overlay gateway), backup, integration, GPU, search, me/whoami. Use for Olares Settings, role, VPN ACL, overlay gateway, backup, integration accounts, language. |
| compatibility | Requires olares-cli on PATH and active Olares profile |
| metadata | {"openclaw":{"requires":{"bins":["olares-cli"]}}} |
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.
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 (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. The accelerator section is version-split: gpu on Olares 1.12.5 (legacy HAMI), compute on 1.12.6+ (see the per-area table) — they are the same Settings slot across versions, not two extra areas:
users appearance apps integration vpn network
gpu / compute 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 |
apps | references/olares-settings-apps.md (entrances / domain / policy / auth-level pipeline) |
vpn | references/olares-settings-vpn.md (ACL deltas, SSH / subroutes / public-domain-policy) |
integration | references/olares-settings-integration.md (`accounts add awss3 |
backup | 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 frp / hosts-file; reverse-proxy get/set (owner set); overlay gateway status / enable / disable (owner) / app enable |
gpu | olares-cli settings gpu --help (read-only list; legacy, 1.12.5 only HAMI /api/gpu/list — removed in 1.12.6: the CLI fails fast there and points at compute list) |
compute | olares-cli settings compute --help (1.12.6+ new "Accelerator": list, unbind <app>, set-type <node> <device>; version-gated, replaces gpu list. <node>/<device> come from list's node header + DEVICE-ID column) |
video | olares-cli settings video --help (read-only config get) |
search | olares-cli settings search --help (status, rebuild, dirs list/add/rm). dirs = the full-content index directories; status shows the index Status plus a full-text-extraction Failures count (-o json for per-file detail). Exclude-pattern view/edit is SPA-only (the CLI's settings search excludes is not wired up). The index coverage model (what's indexed by filename vs full-text, and the defaults) lives once in olares-search |
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 |
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
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; compute list, compute unbind, compute set-type; 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 |
| Owner only | network reverse-proxy set (BFL owner-gated), network overlay enable, network overlay disable |
| 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; network overlay status, network overlay app enable, network overlay app disable; 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 / dirs add / dirs rm / rebuild; backup plans list, backup snapshots list; restore plans list; `advanced env (system |
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 |
network overlay | GET /api/system/overlay-gateway-status/{user}, POST /api/command/{enable,disable}-overlay-gateway, POST /api/command/{enable,disable}-app-overlay-gateway (user-service → olaresd) — 1.12.6+ only (client-side version-gated; on 1.12.5 these routes 404, so the CLI rejects up front) | BFL {code,message,data} envelope. Status data: {status, disable, disable_reason, supported_apps[], error_message}; each app: {app_name, app_id, enabled, shared_app, underlay_networks[]}. status path {user} must be the current user (daemon itsMe); -o json for per-port workload/protocol/description |
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 | /api/launcher-public-domain-access-policy | Already-unwrapped `{deny_all: 0 |
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 and work the same way, but have not yet been smoke-tested against a live instance — treat their result as provisional and confirm the outcome after running.
| Area | Verb | Status |
|---|
network overlay | enable / disable (owner; gateway master switch, async — status settles at on/off; --watch polls until it settles) | VERIFIED |
network overlay | app enable <app> / app disable <app> (any user; auto-restarts the app when running, via market restart; --watch polls until enabled+IP assigned / disabled) | VERIFIED |
appearance | language set <code> | VERIFIED |
users | create / delete (with --watch) | VERIFIED |
search | rebuild, dirs add / rm | VERIFIED (rebuild + dirs writes) |
vpn ssh | enable / disable | VERIFIED |
vpn acl | add / remove | VERIFIED |
integration accounts | add awss3 / add tencent / delete | VERIFIED |
apps | suspend [--cascade] / resume (thin aliases over market stop / market resume) | VERIFIED |
apps | env set, domain set/finish, policy set, auth-level set | UNVERIFIED |
compute | unbind <app> (unbind + stop app), set-type <node> <device> --type X (may stop bound apps; handles bound-apps-stop-blocked) — 1.12.6+ | VERIFIED |
backup | password set | UNVERIFIED |
Not yet implemented (and the CLI deliberately does NOT register them):
- App lifecycle (
install / uninstall / upgrade / stop / resume / cancel / clone) → use olares-market 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) — note the overlay-gateway writes are NOT in this bucket: they only need Authorization (plus RequireOwner on the gateway master switch), so network overlay enable/disable and overlay app enable/disable ARE implemented
- 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 — 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.
Common errors
| Symptom | 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 |
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") |
Any auth / token error (token invalidated, no access token, refresh expired) → see the ../olares-shared/SKILL.md auth error recovery table.
