Foundation for every other olares-cli skill. Every business verb under cluster / files / market / settings / dashboard rides the active profile's token. Read this first.
> Source of truth for flags & syntax is always olares-cli . This file only carries what --help cannot give: the profile mental model, agent-driven login flow, token-storage backends, refresh semantics, and the error → fix matrix.
One profile = one Olares instance + one user identity, keyed by olaresId (e.g. alice@olares.com). Each profile owns its own access_token / refresh_token pair, stored in the OS keychain.
| Command | Purpose |
|---------|---------|
| olares-cli profile login | Mode A — password (+ TOTP if 2FA is on); auto-creates the profile on first run |
| olares-cli profile import | Mode B — bootstrap an access_token from an existing refresh_token |
| olares-cli profile list | List every profile, mark the current one, show login status per profile |
| olares-cli profile use | Switch the current profile; - reverts to the previous one (like cd -) |
| olares-cli profile remove | Delete a profile and its stored token in one shot |
> There is no auth login / auth logout namespace and no per-invocation --profile override flag. Everything lives under profile. "Logout" is profile remove. Identity is whichever profile is currently selected; to target a different one, run olares-cli profile use first.
olares-cli profile login --olares-id <olaresId>
--password-stdin; if 2FA is on, you MUST also pass --totp --password </code> flag</strong> — passwords are never accepted on the command line.
</li></ul><h3>Mode B — existing refresh_token
</h3><pre><code>olares-cli profile import --olares-id <olaresId> --refresh-token "$OLARES_REFRESH_TOKEN"
</code></pre><p>Exchanges the refresh_token for an access_token once via <code>/api/refresh</code> and writes both to the keychain. <strong>Read the token from an env var or secret manager — never inline plaintext.</strong>
</p><h3>Agent-driven login (recommended)
</h3><p>When you (an AI agent) drive the login on the user's behalf, do NOT pass password / TOTP as command-line arguments. Spawn <code>olares-cli profile login --olares-id <id></code> as a background process so it parks at the password prompt, forward the prompt to the user, and read its output after the command exits to confirm success.
</p><h2>Switching and inspecting profiles
</h2><p><code>profile list</code> output:
</p><pre><code> NAME OLARES-ID STATUS
* alice alice@olares.com logged-in (23h59m)
bob bob@olares.com expired
eve eve@olares.com invalidated
frank frank@olares.com never
</code></pre><p>| STATUS | Meaning | Recovery |
</p><p>|--------|---------|----------|
</p><p>| <code>logged-in (Xh Ym)</code> | Token valid; column shows time-to-expiry | — |
</p><p>| <code>logged-in</code> | Token present but JWT has no exp claim (can't verify locally) | Trust until the server says no |
</p><p>| <code>expired</code> | JWT exp is in the past | <code>profile login</code> |
</p><p>| <code>invalidated</code> | Server explicitly rejected the refresh leg | <code>profile login</code> directly (no need to <code>profile remove</code> first) |
</p><p>| <code>never</code> | No token has ever been stored | <code>profile login</code> or <code>profile import</code> |
</p><p>The leading <code>*</code> marks the current profile. <code>profile use</code> accepts either the NAME alias or the olaresId.
</p><h2>Token storage
</h2><p>| OS | Backend | Location |
</p><p>|------|---------|----------|
</p><p>| darwin | macOS Keychain | service <code>olares-cli</code>, account = olaresId |
</p><p>| linux | AES-256-GCM file | under <code>~/.local/share/olares-cli/</code> |
</p><p>| windows | DPAPI | <code>HKCU\Software\OlaresCli\keychain</code> |
</p><p>After <code>login</code> / <code>import</code> succeeds, the CLI prints <code>token stored via <backend> (service "olares-cli", account "<id>")</code>. If the backend resolves to <code>file-fallback</code> (sandboxed / CI environments), be aware the token now sits in a file with <strong>different security properties than the system keychain</strong>.
</p><p>> <strong>The plaintext <code>~/.olares-cli/tokens.json</code> from older builds is deprecated</strong> — if a user upgraded and suddenly appears "logged out", <code>profile login</code> is the fix.
</p><h2>Re-authentication rules
</h2><p><code>profile login</code> and <code>profile import</code> both reject the case "a still-valid token already exists for this olaresId" — to force-overwrite, run <code>profile remove <id></code> first. Expired / invalidated / never-logged-in profiles get the new token written in place; this lets scripts call <code>login</code> after <code>invalidated</code> without an extra <code>remove</code> step.
</p><h2>Automatic token refresh
</h2><p><strong>The CLI rotates expired access_tokens transparently.</strong> Users do NOT need to run <code>profile login</code> just because their access_token aged out — only when the <em>refresh_token itself</em> becomes invalid.
</p><ul><li>Replayable requests (every JSON verb, <code>files cat</code>, <code>files download</code>, <code>files rm</code>, <code>market</code> verbs, …): on 401/403 the transport calls <code>/api/refresh</code> and retries once with the new token.
</li><li>Streaming uploads (<code>files upload</code> chunks): pre-decode the JWT exp; if within 60s of expiry, refresh BEFORE sending, because once a <code>*os.File</code> chunk is consumed it can't be replayed on a 401.
</li></ul><p>Across goroutines AND across concurrent <code>olares-cli</code> processes, <code>/api/refresh</code> is hit at most once per stale token (in-process mutex + cross-process flock).
</p><p>> <strong>Do not implement custom retry/backoff loops on top of auth errors.</strong> Once you see <code>ErrTokenInvalidated</code> or <code>ErrNotLoggedIn</code>, only <code>profile login</code> / <code>profile import</code> will help.
</p><h2>Auth error recovery table
</h2><p>| Error message (excerpt) | Meaning | Fix |
</p><p>|-------------------------|---------|-----|
</p><p>| <code>refresh token for <id> became invalid at <ts></code> | <code>/api/refresh</code> returned 401/403 — the grant is dead | <code>olares-cli profile login --olares-id <id></code> |
</p><p>| <code>no access token for <id></code> | Profile selected but keychain has no entry | <code>olares-cli profile login</code> or <code>profile import</code> |
</p><p>| <code>server rejected the access token (HTTP 401)</code> / <code>(HTTP 403)</code> | After auto-refresh the server still rejects (rare) | <code>olares-cli profile login --olares-id <id></code> |
</p><p>| <code>--olares-id is required</code> | login / import invoked without olaresId | Add <code>--olares-id <id></code> |
</p><p>| <code>already authenticated for <id> (expires in ...)</code> | Still-valid token exists | <code>olares-cli profile remove <id></code> then re-run |
</p><p>| <code>a token is already stored for <id> but its expiry can't be determined client-side</code> | Token present but JWT carries no exp claim | <code>profile remove <id></code> then re-run |
</p><p>| <code>two-factor authentication required: re-run with --totp <code></code> | 2FA on, non-TTY context | Re-run with <code>--totp <code></code>, or run interactively |
</p><p>| <code>password is empty</code> / <code>TOTP code is empty</code> | stdin / TTY returned an empty string | Check for premature EOF or an empty pipe |
</p><p>| <code>profile <name> not found</code> | <code>profile use</code> / <code>profile remove</code> referenced an unknown profile | <code>profile list</code> to see the actual names |
</p><p>> <strong>Do not silently retry auth errors.</strong> 401/403 after auto-refresh and <code>already authenticated</code> are deterministic — follow the table; blind retries make it worse.
</p><h2>Security rules
</h2><ul><li><strong>Never</strong> invent a <code>--password <plaintext></code> argument (it does not exist). Passwords go through the TTY or <code>--password-stdin</code> fed by a secret pipe.
</li><li><strong>Never</strong> echo <code>access_token</code> / <code>refresh_token</code> to the terminal. When passing a refresh_token to <code>profile import</code>, source it from an environment variable: <code>--refresh-token "$OLARES_REFRESH_TOKEN"</code>.
</li><li><strong>Confirm intent before write/delete actions</strong> (<code>profile remove</code>, <code>files rm</code>, <code>files upload --overwrite</code>, <code>cluster pod delete</code>, …). Do not act unilaterally on the user's behalf.
</li><li><strong>TOTP is not a password</strong> — it is single-use and short-lived, so the CLI echoes it to make manual entry less error-prone. Never persist a TOTP in a shared script.
</li></ul></div>
</div>
</div>
<div id="tab-versions" class="detail-content">
<div class="detail-section">
<h2>版本历史</h2>
<p style="margin-bottom:12px;font-size:14px;color:#94a3b8;">共 3 个版本</p>
<ul class="version-list">
<li>
<div>
<span class="version-tag">v4.0.1</span>
<span style="font-size:11px;color:#5b6abf;margin-left:8px;background:#eef0ff;padding:1px 8px;border-radius:10px;">当前</span> </div>
<div style="font-size:12px;color:#94a3b8;">
2026-05-29 21:03 安全 安全 </div>
</li>
<li>
<div>
<span class="version-tag">v1.2.0</span>
</div>
<div style="font-size:12px;color:#94a3b8;">
2026-05-29 13:44 </div>
</li>
<li>
<div>
<span class="version-tag">v1.1.0</span>
</div>
<div style="font-size:12px;color:#94a3b8;">
2026-05-08 02:59 安全 安全 </div>
</li>
</ul>
</div>
</div>
<div id="tab-security" class="detail-content">
<div class="detail-section">
<h2>安全检测</h2>
<div class="sec-grid"> <div class="sec-card">
<h4>腾讯云安全 (Keen)</h4>
<div class="sec-status sec-safe">
安全，无风险 </div>
<a href="https://tix.qq.com/search/skill?keyword=74821fbe5a99ce3e36a5b86c5305489b" target="_blank">查看报告</a> </div>
<div class="sec-card">
<h4>腾讯云安全 (Sanbu)</h4>
<div class="sec-status sec-safe">
安全，无风险 </div>
<a href="https://static.cloudsec.tencent.com/html-report-v2/2026/05/29/471804_2d847c09230a2f6c4544b26a74922e45.html?q-sign-algorithm=sha1&q-ak=AKID8JMG1bzBC1dz96qNhssfFftujT1NCoFi&q-sign-time=1781545018%3B1813081018&q-key-time=1781545018%3B1813081018&q-header-list=host&q-url-param-list=&q-signature=7ae4f828bc17aa3135954a1035719ba2d15e8081" target="_blank">查看报告</a> </div>
</div>
</div>
</div>
<!-- Recommended Skills -->
<div style="margin-top:24px;">
<h2 style="font-size:18px;font-weight:600;margin-bottom:16px;">🔗 相关推荐</h2>
<div class="rec-grid">
<div class="rec-card">
<span class="badge-cat" style="margin-bottom:8px;display:inline-block;"></span>
<h3><a href="/s/olares-dashboard">Olares Dashboard (olares-cli dashboard)</a></h3>
<div class="rec-owner">olares</div> <div class="rec-desc">Olares Dashboard（olares‑cli dashboard）— 通过命令行查询 Olares Dashboard SPA 的概览与应用路由，限定在当前活动的 Olare 实例。</div>
<div class="rec-stats">
<span style="color:#f39c12;">★ 0</span>
<span style="color:#5b6abf;">📥 464</span>
</div>
</div>
<div class="rec-card">
<span class="badge-cat" style="margin-bottom:8px;display:inline-block;"></span>
<h3><a href="/s/olares-settings">Olares Settings (olares-cli settings)</a></h3>
<div class="rec-owner">olares</div> <div class="rec-desc">Olares Settings (olares-cli settings) — read and mutate Olares Settings UI surfaces from the command line, scoped to the</div>
<div class="rec-stats">
<span style="color:#f39c12;">★ 0</span>
<span style="color:#5b6abf;">📥 452</span>
</div>
</div>
<div class="rec-card">
<span class="badge-cat" style="margin-bottom:8px;display:inline-block;"></span>
<h3><a href="/s/olares-files">Olares Files (olares-cli files)</a></h3>
<div class="rec-owner">olares</div> <div class="rec-desc">Olares Files (olares-cli files) — 通过命令行管理 Olares 系统中的文件，作用于当前活动的 Olares ID。支持列出 (ls)、上传、下载等操作。</div>
<div class="rec-stats">
<span style="color:#f39c12;">★ 0</span>
<span style="color:#5b6abf;">📥 483</span>
</div>
</div>
</div>
</div>
</div>
<script>
document.addEventListener('DOMContentLoaded',function(){
document.querySelectorAll('.detail-tab').forEach(function(btn){
btn.addEventListener('click',function(e){
var tab = this.getAttribute('data-tab');
document.querySelectorAll('.detail-tab').forEach(function(b){b.classList.remove('active')});
document.querySelectorAll('.detail-content').forEach(function(c){c.classList.remove('active')});
this.classList.add('active');
var el = document.getElementById('tab-'+tab);
if(el) el.classList.add('active');
});
});
});
</script>
<div class="footer">
<p>Skill工具集 © 2026</p>
</div></body>
</html>