olares-cli shared rules
Read this thin front door before a runtime skill. It supplies suite routing, the active-profile model, platform entry points and the auth proceed/stop rule. Load detailed references only when the current task triggers them.
If olares-cli is not on PATH
Every command in this suite needs it, and the binary carries this suite, so a machine with the skills but no binary got them from a registry rather than from a release. Install it, then have it write the skills that match itself:
npm install -g @olares/cli@latest
olares-cli skills install
This installs a client, not Olares itself: it operates an existing Olares instance over the network and does not create one. An Olares host already has the binary at /usr/local/bin/olares-cli with the host-side node / os / gpu trees this suite does not use.
Platform entry points
- Olares platform model: userspace storage, uid/gid 1000, protected Home directories, app/namespace networking, system middleware and Olares version semantics. Read it for files, chart, cluster or settings tasks that touch those concepts.
- Application state machine: lifecycle transitions, allowed operations, backend timeouts, serialized downloads,
running semantics and unreliable progress. Read it for market operations or runtime diagnosis.
- Profile and authentication: login/import flows, profile statuses, token storage and refresh behavior. Read it only for profile work or auth recovery.
Skill suite map
| Skill |
Use it for |
olares-shared |
Suite routing, platform entry points, profile/auth decisions |
olares-market |
Install and manage catalog/uploaded apps; lifecycle and chart transfer |
olares-settings |
Post-install app/system configuration, users, VPN, backup and integrations |
olares-cluster |
Runtime objects, logs, jobs, namespaces, nodes and middleware |
olares-dashboard |
CPU, memory, disk, network, pod, GPU and fan metrics |
olares-files |
Browse and modify Drive, Sync, cache, external and cloud files |
olares-knowledge |
URL, yt-dlp, aria2, torrent and Hugging Face download tasks |
olares-search |
Full-content file search and installed-app title search |
olares-router |
Configure, install, call and diagnose models through Router |
olares-chart |
Author, validate and deploy an app's Olares chart |
olares-publish |
Prepare and submit a public Olares Market listing |
olares-doctor |
Diagnose an app/system runtime failure and route the fix |
Porting and debugging an app commonly combines chart (author/fix), market (lifecycle), this skill's platform model and doctor (root-cause diagnosis).
Host installation, node joining, OS upgrades and GPU drivers use the kubeconfig-backed olares-cli node / os / gpu trees, not this profile-backed skill suite.
Active profile
One profile selects one Olares instance and one Olares identity. Every profile-backed command targets that selection; there is no per-command --profile override.
| Command |
Purpose |
olares-cli profile list |
Show profiles, current selection, auth status and cached Olares version |
olares-cli profile use <name|-> |
Switch selection; - returns to the previous profile |
olares-cli profile login |
Authenticate with password and optional TOTP |
olares-cli profile import |
Bootstrap from a refresh token |
olares-cli profile remove <name> |
Remove a profile and its credential |
Use olares-cli profile --help for flags and the auth reference for login or recovery.
Auth-readiness gate
Proceed by default:
logged-in and expired proceed; an expired access token normally refreshes on the next request.never and invalidated stop for profile login or profile import.- For
unknown or an unparseable token, run the business command and react to its typed error instead of guessing.
Do not preflight every command. The CLI refreshes and retries an authentication rejection once. Stop for login when the CLI explicitly says the credential is absent/invalidated or prints a login action after a persistent 401/459. A 403 permission denial, network error or 5xx is not a login signal. Never build a retry loop around auth errors.
Security and task scope
- Never place a password in command arguments. Use the interactive prompt or
--password-stdin.
- Never print access or refresh tokens. Source imports from a secret environment variable or secret manager.
- Ask before login, credential replacement, an ambiguous target or an action outside the user's authorised task scope.
- Within an authorised chart deploy/debug task, install, upgrade, restart, uninstall and clean reinstall are normal loop steps; do not ask again for each command.
1---2name: olares-shared3description: Foundation for the olares-cli skill suite: choose the right domain skill, understand the Olares platform model each task depends on, and decide whether the active profile can proceed or needs login recovery. Use first for runtime skills, and directly for Olares ID, profile, login, 2FA/TOTP, refresh token, keychain, auth errors, or uncertainty about which Olares skill owns a task.4---5
6# olares-cli shared rules
7
8Read this thin front door before a runtime skill. It supplies suite routing, the active-profile model, platform entry points and the auth proceed/stop rule. Load detailed references only when the current task triggers them.
9
10## If olares-cli is not on PATH
11
12Every command in this suite needs it, and the binary carries this suite, so a machine with the skills but no binary got them from a registry rather than from a release. Install it, then have it write the skills that match itself:
13
14```bash
15npm install -g @olares/cli@latest
16olares-cli skills install
17```
18
19This installs a client, not Olares itself: it operates an existing Olares instance over the network and does not create one. An Olares host already has the binary at `/usr/local/bin/olares-cli` with the host-side `node` / `os` / `gpu` trees this suite does not use.
20
21## Platform entry points
22
23- [Olares platform model](references/olares-platform.md): userspace storage, uid/gid 1000, protected Home directories, app/namespace networking, system middleware and Olares version semantics. Read it for files, chart, cluster or settings tasks that touch those concepts.
24- [Application state machine](references/olares-platform-appstate.md): lifecycle transitions, allowed operations, backend timeouts, serialized downloads, `running` semantics and unreliable progress. Read it for market operations or runtime diagnosis.
25- [Profile and authentication](references/olares-auth.md): login/import flows, profile statuses, token storage and refresh behavior. Read it only for profile work or auth recovery.
26
27## Skill suite map
28
29| Skill | Use it for |
30|---|---|
31| [`olares-shared`](SKILL.md) | Suite routing, platform entry points, profile/auth decisions |
32| [`olares-market`](../olares-market/SKILL.md) | Install and manage catalog/uploaded apps; lifecycle and chart transfer |
33| [`olares-settings`](../olares-settings/SKILL.md) | Post-install app/system configuration, users, VPN, backup and integrations |
34| [`olares-cluster`](../olares-cluster/SKILL.md) | Runtime objects, logs, jobs, namespaces, nodes and middleware |
35| [`olares-dashboard`](../olares-dashboard/SKILL.md) | CPU, memory, disk, network, pod, GPU and fan metrics |
36| [`olares-files`](../olares-files/SKILL.md) | Browse and modify Drive, Sync, cache, external and cloud files |
37| [`olares-knowledge`](../olares-knowledge/SKILL.md) | URL, yt-dlp, aria2, torrent and Hugging Face download tasks |
38| [`olares-search`](../olares-search/SKILL.md) | Full-content file search and installed-app title search |
39| [`olares-router`](../olares-router/SKILL.md) | Configure, install, call and diagnose models through Router |
40| [`olares-chart`](../olares-chart/SKILL.md) | Author, validate and deploy an app's Olares chart |
41| [`olares-publish`](../olares-publish/SKILL.md) | Prepare and submit a public Olares Market listing |
42| [`olares-doctor`](../olares-doctor/SKILL.md) | Diagnose an app/system runtime failure and route the fix |
43
44Porting and debugging an app commonly combines `chart` (author/fix), `market` (lifecycle), this skill's platform model and `doctor` (root-cause diagnosis).
45
46Host installation, node joining, OS upgrades and GPU drivers use the kubeconfig-backed `olares-cli node` / `os` / `gpu` trees, not this profile-backed skill suite.
47
48## Active profile
49
50One profile selects one Olares instance and one Olares identity. Every profile-backed command targets that selection; there is no per-command `--profile` override.
51
52| Command | Purpose |
53|---|---|
54| `olares-cli profile list` | Show profiles, current selection, auth status and cached Olares version |
55| `olares-cli profile use <name\|->` | Switch selection; `-` returns to the previous profile |
56| `olares-cli profile login` | Authenticate with password and optional TOTP |
57| `olares-cli profile import` | Bootstrap from a refresh token |
58| `olares-cli profile remove <name>` | Remove a profile and its credential |
59
60Use `olares-cli profile --help` for flags and [the auth reference](references/olares-auth.md) for login or recovery.
61
62## Auth-readiness gate
63
64Proceed by default:
65
66- `logged-in` and `expired` proceed; an expired access token normally refreshes on the next request.
67- `never` and `invalidated` stop for `profile login` or `profile import`.
68- For `unknown` or an unparseable token, run the business command and react to its typed error instead of guessing.
69
70Do not preflight every command. The CLI refreshes and retries an authentication rejection once. Stop for login when the CLI explicitly says the credential is absent/invalidated or prints a login action after a persistent 401/459. A 403 permission denial, network error or 5xx is not a login signal. Never build a retry loop around auth errors.
71
72## Security and task scope
73
74- **Never** place a password in command arguments. Use the interactive prompt or `--password-stdin`.
75- **Never** print access or refresh tokens. Source imports from a secret environment variable or secret manager.
76- Ask before login, credential replacement, an ambiguous target or an action outside the user's authorised task scope.
77- Within an authorised chart deploy/debug task, install, upgrade, restart, uninstall and clean reinstall are normal loop steps; do not ask again for each command.
beclab