frely-cli 0.23.0 → 0.23.2

package/README.md

@@ -1,8 +1,10 @@
-# frely-cli
+# Frely CLI
 
-[English](README.md) · [简体中文](README.zh-CN.md)
+[![Frely CLI: let agents access your device from any location](site/assets/og.png)](https://cli.frely.cloud/)
 
-`frely-cli` turns a computer you choose into a device that AI agents can work on from anywhere. ChatGPT, Claude, Codex and other MCP clients connect through **FrelyMCP** and use the files, shell commands and processes in the folders you allow. The computer connects out to Frely, so you open no ports.
+[Website](https://cli.frely.cloud/) · [Docs](https://cli.frely.cloud/docs/) · [Frely](https://frely.cloud/) · [English](README.md) · [简体中文](README.zh-CN.md)
+
+Frely CLI (`frely-cli`) connects a computer you choose to **FrelyMCP**, so ChatGPT, Claude, Codex and other MCP clients can work on it from anywhere. They use the files, shell commands and processes in the folders you allow. The computer connects out to Frely, so you open no ports.
 
 It is also the command line for your Frely account:
 
@@ -15,20 +17,13 @@ It is also the command line for your Frely account:
 
 ### A server, with a Frely account (no browser)
 
-Get a one-time install command and paste it on the server. It installs `frely`, signs in to your account, enables Device MCP and starts the background service. Nothing opens in a browser and nothing asks a question.
-
-Get the command in either place:
-
-- On the Frely website: **My Devices → Add a computer → Create install command**.
-- In ChatGPT or Claude connected to FrelyMCP: ask it to add a computer. `list_devices` returns the command.
-
-It looks like this:
+Get a one-time install command on the Frely website (**My Devices → Add a computer → Create install command**), or ask ChatGPT or Claude connected to FrelyMCP to add a computer. Paste it on the server:
 
 ```sh
 curl -fsSL https://frely.cloud/start.sh | FRELY_INSTALL_TOKEN=fit_... sh
 ```
 
-The token works once and expires after 15 minutes. It is not saved on the computer. If the computer already has Frely installed or signed in, the command updates it and switches the sign-in to your account. On Linux, run `sudo loginctl enable-linger $USER` so the service stays online after you log out of SSH.
+It installs `frely`, signs in to your account, enables Device MCP and starts the background service. The token works once and expires after 15 minutes. On Linux, run `sudo loginctl enable-linger $USER` so the service stays online after you log out of SSH. [More](https://cli.frely.cloud/docs/help/install-on-a-server/)
 
 ### A computer with a browser
 
@@ -42,23 +37,21 @@ curl -fsSL https://frely.cloud/start.sh | sh
 curl.exe -fsSLo "$env:TEMP\frely-start.ps1" https://frely.cloud/start.ps1; powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\frely-start.ps1"
 ```
 
-The script installs the latest `frely`, then runs `frely mcp start`: it opens the browser to sign in (new accounts can register on the same page), asks you to approve this device and prints your MCP URL. Run it again any time to update; it restarts the background service on the new version.
-
-The workspace is your home directory by default (credential and shell start-up files stay protected). Set `FRELY_WORKSPACE=/path` to share another folder, and `FRELY_INSTALL_DIR` to install somewhere other than `~/.local/bin`.
+The script installs the latest `frely`, opens the browser to sign in (new accounts can register there), asks you to approve this device and prints your MCP URL. Run it again any time to update. The workspace is your home directory by default; set `FRELY_WORKSPACE=/path` to share another folder. [More](https://cli.frely.cloud/docs/help/how-do-i-install/)
 
-### Let your agent set it up (no device access)
+### Let your agent set it up
 
-Ask an agent that has a shell (Claude Code, Codex, pi) to install the CLI, sign in with `frely login --email`, and run `frely skill install --host <host>` (add `--scope project --dir <project>` for one project). The `frely` Skill it installs teaches the agent to use your account (`frely api`), install marketplace items and Agents, and to offer FrelyMCP only when a request needs it (another computer, Cloud MCPs, a browser, a client without a shell). This path does not open this computer to remote clients; `frely mcp start` does.
+Ask an agent that has a shell (Claude Code, Codex, pi) to install the CLI, sign in with `frely login --email`, and run `frely skill install --host <host>`. The `frely` Skill teaches the agent to use your account and to offer FrelyMCP only when a request needs it. This path does not open this computer to remote clients; `frely mcp start` does.
 
 ### Install only
 
-`install.sh` and `install.ps1` (same URLs, `https://frely.cloud/install.sh`) only install the program, for scripts, Skills and agents that need the CLI. Or use npm (Node.js 22 or newer):
+`https://frely.cloud/install.sh` and `install.ps1` only install the program, for scripts and agents that need the CLI. Or use npm (Node.js 22 or newer):
 
 ```sh
 npm install --global --ignore-scripts frely-cli@latest
 ```
 
-The installers pick the right executable for your platform, check its SHA-256 and install into your user directory without Node.js. They download from GitHub Releases first and fall back to npmmirror and npmjs (`@frelyhq/cli-<platform>`) when GitHub is slow or unreachable. `FRELY_INSTALL_SOURCES` changes the order.
+The installers check the SHA-256 and download from GitHub Releases first, then npmmirror and npmjs. [More](https://cli.frely.cloud/docs/help/install-only/)
 
 ## Common commands
 
@@ -68,147 +61,48 @@ The installers pick the right executable for your platform, check its SHA-256 an
 | `frely mcp status` | Show the MCP URL, workspace, authorization expiry and service state. |
 | `frely mcp workspace add <path>` | Share another folder. `frely mcp workspace list` shows them all. |
 | `frely mcp stop` / `frely mcp start` | Pause or resume the background service. |
+| `frely mcp auto-update [on\|off]` | Let the background service update itself while idle (macOS/Linux, off by default). |
 | `frely mcp remove` | Revoke access for every client and uninstall the service. |
 | `frely doctor` | Check sign-in, installation, service and connection. `-v` for details. |
 | `frely update` | Update to the latest version in place. |
 | `frely login` / `frely logout` | Sign in or out of your Frely account. |
+| `frely sandbox proxy <url>` | Forward the command sandbox's network traffic to your own HTTP(S) proxy. Without it the CLI uses `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` and, on macOS, the system proxy. `--clear` removes it; restart the service to apply. |
+| `frely tunnel <host>:<port>` | Inside a sandboxed command: listen on `127.0.0.1` and forward TCP connections to `host:port` through the sandbox, for database and redis clients. `--local-port N` picks the local port. |
 | `frely uninstall` | Remove Frely from this computer (lists everything first). |
 
-Run any command group without a subcommand (for example `frely mcp` or `frely agent`) to see what it offers.
+All commands and options: [command reference](https://cli.frely.cloud/docs/help/commands/). `frely help --agent --json` prints the full machine-readable contract.
 
-## Use frely-cli with FrelyMCP
+## Use with FrelyMCP
 
-FrelyMCP is one MCP address for your whole account: `https://mcp.frely.cloud/mcp`. Every computer where you ran `frely mcp start` appears behind it. `frely-cli` runs the tools on each computer; the AI client only needs the URL.
+FrelyMCP is one MCP address for your whole account: `https://mcp.frely.cloud/mcp`. Every computer where you ran `frely mcp start` appears behind it.
 
-### Connect a client
-
-1. On the computer to control, run `frely mcp start` (the install scripts above already do this). It prints the MCP URL.
+1. On the computer to control, run `frely mcp start` (the install scripts above already do this).
 2. Add the URL to your client as a remote MCP server with OAuth:
    - ChatGPT or Claude: add a custom connector with the URL.
    - Claude Code on another computer: `claude mcp add --transport http frely "https://mcp.frely.cloud/mcp"`, then open `/mcp` to authorize.
 3. Sign in to Frely and approve the client.
 
-To check the connection, ask the client to list the top-level names in your workspace. A result that matches the folder means it works.
-
-### What the AI can do
-
-- `list_devices` shows your computers, whether each is online and its workspaces. If you have none, it gives the install command above.
-- Device tools take a `device` argument and run on that computer:
-  - `read`: list, read, search and find files in the workspace.
-  - `edit_file`: write whole files or edit lines, atomically.
-  - `process`: run shell commands, or start and manage long-running processes.
-  - `web_fetch`: read public web pages.
-- `local_mcp_list` and `local_mcp_call` reach MCP servers on that computer that you turned on (see below).
-- `local_models` (background service only) lists model servers on that computer (Ollama, LM Studio, vLLM, llama.cpp) and shares them as a Frely Provider; it uses one Provider slot. Shared models appear in `models_list` marked `local: true`.
-- `frely_list` and `frely_call` manage your Frely account (API keys, credits, plans, orders). `frely api list|describe|call` is the same set from the terminal.
-
-The AI client's own shell still runs where the client runs; ask it to use the Frely tools for work on your computer. All clients share each computer's workspaces and running processes.
-
-### Local MCP servers on this computer
+To check the connection, ask the client to list the top-level names in your workspace.
 
-Servers that listen only on loopback are found automatically (`frely mcp local list`). Add others with:
-
-```sh
-frely mcp local add <name> --url http://127.0.0.1:<port>/mcp
-frely mcp local add <name> [--env KEY=VALUE] -- <command> [args...]   # stdio
-```
-
-Each server stays hidden from remote clients until you turn it on, one by one, on the Frely connections page. Enabled servers run outside the command sandbox with your user account. Only loopback addresses are contacted, and headers and environment values never leave the computer.
-
-### Authorization
-
-Device MCP access lasts 90 days by default; `frely mcp start --days 1..365` renews early. When it expires, `frely mcp start` asks for approval again. The URL never changes. Manage your computers on the Frely website under **My Devices**.
+- **What the AI can do**: `list_devices`, then `read`, `edit_file`, `process` and `web_fetch` on the computer you pick, plus your account through `frely_list` and `frely_call`. [More](https://cli.frely.cloud/docs/help/what-can-the-ai-do/)
+- **Local MCP servers**: loopback servers are found automatically (`frely mcp local list`); each stays hidden until you turn it on in Frely. [More](https://cli.frely.cloud/docs/help/local-mcp-servers/)
+- **Authorization**: access lasts 90 days by default; `frely mcp start --days 1..365` renews early. The URL never changes. [More](https://cli.frely.cloud/docs/help/authorization-expiry/)
 
 ## More features
 
-### Invoke a Frely-hosted Agent
-
-```sh
-frely agent install <distribution-id> --host claude-code --scope global
-printf '%s' 'Your complete task' | frely agent run <distribution-id> --input-stdin --json
-```
-
-`--host` is one of `chatgpt`, `codex`, `claude-code`, `pi` or `generic`. A full manifest URL also works in place of the id. To use a Creator's sponsored API key instead of your account, pass it on stdin with `--api-key-stdin`; it is stored in the secure credential store, never in the Skill. Use short-lived, single-model keys with a bounded quota. `frely agent status <id>` shows the Skill and the key's budget; `frely agent remove <id>` removes both.
+- **Frely-hosted Agents**: `frely agent install <distribution-id> --host claude-code` installs an Agent as a local Skill; `frely agent run` calls it. [More](https://cli.frely.cloud/docs/help/install-agents-and-items/)
+- **Marketplace Prompts and Skills**: `frely item install <item-id> --host claude-code`. Paid parts install only when your account holds a pass. [More](https://cli.frely.cloud/docs/help/install-agents-and-items/)
+- **Local model sharing**: `frely provider share ollama` publishes a loopback model server as your personal Frely Provider. [More](https://cli.frely.cloud/docs/help/share-local-model/)
+- **Your account from the terminal**: `frely api list|describe|call`. [More](https://cli.frely.cloud/docs/help/manage-account-from-cli/)
 
-### Install marketplace Prompts and Skills
-
-```sh
-frely item install <item-id> --host claude-code
-```
-
-The first call opens a browser for Frely Cloud authorization. A paid part is installed only if your account holds a pass; otherwise the command says how to buy one. Skills go to the host's Skill folder under their own name (with `--scope project`, `--dir` is the project root; default: current directory), Prompts to `--dir`, and scripts are saved without execute permission. Nothing is added to the Skill folder: what Frely wrote is tracked under `~/.config/frely`. Frely never overwrites a folder it did not install or a file you edited. A Skill that Frely's scan has not passed is reported as such: read it before use, then `frely item trust <folder>` remembers the review; a new version needs a new review.
-
-Cloud MCPs you buy are not installed on the computer: enable them for a connection on the Frely website and their tools appear in FrelyMCP.
-
-### Local model sharing
-
-```sh
-frely provider share ollama
-frely provider share openai-compatible --url http://127.0.0.1:8080/v1 --models model-a,model-b --name "Local GPU"
-frely provider list
-```
-
-This publishes a loopback OpenAI-compatible endpoint (Ollama by default at `http://127.0.0.1:11434/v1`) as a personal Frely Provider, using one empty personal Provider slot. With no empty slot, or with `--creator`, it creates a Creator Provider counted against your Creator plan, and its models can be the base of Agents you publish. Keep the computer online while it is used, and make sure the runtime returns `usage`. If setup stops halfway, run the same command again to resume.
-
-## Local execution boundaries
-
-- **Files**: file tools stay inside the shared workspaces, reject symlink escapes, cap reads and writes at 1 MiB and write atomically. Credential stores and shell start-up files are protected even inside the home directory.
-- **Commands**: `process` runs as your OS user inside an OS sandbox. Credential folders are unreadable, writes are limited to the workspace and the temp directory, and network goes through a proxy. If the computer cannot sandbox (Windows, or Linux without `bubblewrap`, `socat` and `ripgrep`), commands are refused rather than run unsandboxed. You can open more on the Frely connections page: credential folders to read, extra folders to write, or a time-limited run without the sandbox. `FRELY_SANDBOX=off` turns the sandbox off on the device.
-- **Credentials**: the MCP URL contains no secret. Clients hold OAuth tokens; the CLI holds a separate MCP execution key, encrypted with a master key in macOS Keychain, Windows Credential Manager or Linux Secret Service. Headless machines can set `FRELY_CREDENTIAL_KEY` (32 bytes) with `FRELY_CREDENTIAL_STORE=encrypted-file`. When authorization expires, requests and queued work stop; finished writes are not undone.
-
-Details: [credential and installation boundaries](docs/credential-storage.md).
-
-## Update, diagnose and uninstall
-
-```sh
-frely doctor      # account, installation, latest version, MCP and service state
-frely doctor -v   # + config paths, authorization expiry, last heartbeat, sanitized errors
-frely update      # update in place, keeping your login, device, URL and workspace
-frely uninstall   # list everything, then remove it after you type yes (--yes for scripts)
-```
-
-`frely update` keeps the original install method and never downgrades. It pauses the background service, replaces the program after checking it, and restarts the service. On Windows it prints a PowerShell command to run in a local terminal. See [self-update](docs/self-update.md) and [service maintenance](docs/service-maintenance.md).
-
-`frely uninstall` revokes this computer's access on the Frely side, removes the service, saved login, device identity, settings, caches and the Agent Skills Frely installed, and finally removes the `frely` program. It keeps the Frely App, your Providers and Agents in your account, the PATH lines the installer added, Skills you edited and marketplace items. Run it in a local terminal, not through Device MCP.
-
-## All commands
-
-```text
-frely login [--relay <https-url>] [--no-browser]
-frely login --email <address> [--mcp] [--workspace <path>]   then   frely login --code <6-digit code>
-frely logout
-frely uninstall [--yes] [--json]
-frely doctor [-v] [--json]
-frely update
-frely mcp start [--workspace <path>] [--days 1..365] [--no-browser] [--json]
-frely mcp status [--json]
-frely mcp stop|remove
-frely mcp workspace list [--json]
-frely mcp workspace add|remove <path>
-frely mcp local list [--json]
-frely mcp local add <name> (--url <address> | [--env KEY=VALUE] -- <command> [args...])
-frely mcp local remove <name>
-frely agent install <distribution-id|manifest-url> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--dir <project>] [--api-key-stdin] [--json]
-frely agent run <distribution-id> (--input <text>|--input-stdin) [--json]
-frely agent status (<distribution-id>|--api-key-stdin [--relay <url>]) [--json]
-frely agent remove <distribution-id> [--json]
-frely skill install [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--dir <project>] [--json]
-frely item install <item-id> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--dir <path>] [--json]
-frely item trust <folder> [--check]
-frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id> | --creator] [--name <name>]
-frely provider list [--json]
-frely api list|describe|call
-```
+## Safety
 
-`frely help --agent --json` prints the full machine-readable contract, including commands not shown in `frely --help`: `frely mcp stdio` (serve the tools over stdio to a local client), `frely mcp serve` (the foreground process the service runs) and `frely network` (preview).
+File tools stay inside the shared workspaces and protect credential and shell start-up files. Commands run as your OS user inside an OS sandbox, and are refused where the computer cannot sandbox them. Clients hold OAuth tokens; the CLI keeps its own key in the system credential store. [Is it safe?](https://cli.frely.cloud/docs/help/is-it-safe/) · [Sandbox and permissions](https://cli.frely.cloud/docs/help/sandbox-and-permissions/) · [Credential storage](docs/credential-storage.md)
 
 ## Documentation
 
-- [Device MCP](docs/device-mcp.md)
-- [Device Relay transport](docs/device-transport.md)
-- [MCP OAuth contract](docs/mcp-oauth-relay-contract.md)
-- [`frely api`](docs/api.md)
-- [Frely Network (preview)](docs/frely-network.md)
+- Help: [cli.frely.cloud/docs](https://cli.frely.cloud/docs/) ([update](https://cli.frely.cloud/docs/help/update/), [doctor](https://cli.frely.cloud/docs/help/doctor/), [uninstall](https://cli.frely.cloud/docs/help/uninstall/))
+- Contracts, for contributors: [Device MCP](docs/device-mcp.md) · [Device Relay transport](docs/device-transport.md) · [MCP OAuth contract](docs/mcp-oauth-relay-contract.md) · [`frely api`](docs/api.md) · [Frely Network (preview)](docs/frely-network.md) · [self-update](docs/self-update.md) · [service maintenance](docs/service-maintenance.md)
 
 ## License and trademarks
 

package/README.zh-CN.md

@@ -1,8 +1,10 @@
-# frely-cli
+# Frely CLI
 
-[English](README.md) · [简体中文](README.zh-CN.md)
+[![Frely CLI：让 Agent 从任何地方访问你的设备](site/assets/og.png)](https://cli.frely.cloud/zh/)
 
-`frely-cli` 把你指定的一台电脑变成 AI Agent 可以在任何地方操作的设备。ChatGPT、Claude、Codex 等 MCP 客户端通过 **FrelyMCP** 连接，使用你授权的文件夹里的文件、Shell 命令和进程。电脑主动向 Frely 发起连接，不需要开放任何端口。
+[官网](https://cli.frely.cloud/zh/) · [文档](https://cli.frely.cloud/docs/) · [Frely](https://frely.cloud/) · [English](README.md) · [简体中文](README.zh-CN.md)
+
+Frely CLI（`frely-cli`）把你指定的一台电脑连接到 **FrelyMCP**，让 ChatGPT、Claude、Codex 等 MCP 客户端可以在任何地方操作它，使用你授权的文件夹里的文件、Shell 命令和进程。电脑主动向 Frely 发起连接，不需要开放任何端口。
 
 它也是 Frely 账号的命令行工具：
 
@@ -15,20 +17,13 @@
 
 ### 服务器，已有 Frely 账号（无需浏览器）
 
-拿到一条一次性安装命令，粘贴到服务器上运行。它会安装 `frely`、登录你的账号、开启设备 MCP 并启动后台服务，全程不打开浏览器，也不会提问。
-
-在以下任一处获取命令：
-
-- Frely 网站：**My Devices → Add a computer → Create install command**。
-- 已连接 FrelyMCP 的 ChatGPT 或 Claude：让它添加一台电脑，`list_devices` 会返回这条命令。
-
-命令形如：
+在 Frely 网站 **My Devices → Add a computer → Create install command** 获取一次性安装命令，或让已连接 FrelyMCP 的 ChatGPT、Claude 添加一台电脑。粘贴到服务器上运行：
 
 ```sh
 curl -fsSL https://frely.cloud/start.sh | FRELY_INSTALL_TOKEN=fit_... sh
 ```
 
-令牌只能用一次，15 分钟内有效，不会保存在电脑上。如果这台电脑已经安装或登录过 Frely，命令会更新它，并把登录切换到你的账号。Linux 上请运行 `sudo loginctl enable-linger $USER`，退出 SSH 后服务才能保持在线。
+它会安装 `frely`、登录你的账号、开启设备 MCP 并启动后台服务。令牌只能用一次，15 分钟内有效。Linux 上请运行 `sudo loginctl enable-linger $USER`，退出 SSH 后服务才能保持在线。[详情](https://cli.frely.cloud/docs/help/install-on-a-server/)
 
 ### 有浏览器的电脑
 
@@ -42,167 +37,71 @@ curl -fsSL https://frely.cloud/start.sh | sh
 curl.exe -fsSLo "$env:TEMP\frely-start.ps1" https://frely.cloud/start.ps1; powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\frely-start.ps1"
 ```
 
-脚本安装最新版 `frely`，然后运行 `frely mcp start`：打开浏览器登录（新账号可在同一页面注册），请你批准这台设备，最后输出 MCP URL。随时可以再运行一次来升级，它会用新版本重启后台服务。
+脚本安装最新版 `frely`，打开浏览器登录（新账号可在同一页面注册），请你批准这台设备，最后输出 MCP URL。随时可以再运行一次来升级。工作区默认是用户主目录，设置 `FRELY_WORKSPACE=/path` 可共享其他文件夹。[详情](https://cli.frely.cloud/docs/help/how-do-i-install/)
+
+### 让 Agent 帮你安装
 
-工作区默认是用户主目录（凭据和 Shell 启动文件仍受保护）。设置 `FRELY_WORKSPACE=/path` 可共享其他文件夹，`FRELY_INSTALL_DIR` 可改变安装位置（默认 `~/.local/bin`）。
+让有 Shell 的 Agent（Claude Code、Codex、pi）安装 CLI，用 `frely login --email` 登录，再运行 `frely skill install --host <host>`。安装的 `frely` Skill 会教 Agent 使用你的账号，只在需要时才建议 FrelyMCP。这种方式不会把这台电脑开放给远程客户端，`frely mcp start` 才会。
 
 ### 只安装
 
-`install.sh` 和 `install.ps1`（同一域名，`https://frely.cloud/install.sh`）只安装程序，供脚本、Skill 和 Agent 使用。也可以用 npm（需要 Node.js 22 或更新版本）：
+`https://frely.cloud/install.sh` 和 `install.ps1` 只安装程序，供脚本和 Agent 使用。也可以用 npm（需要 Node.js 22 或更新版本）：
 
 ```sh
 npm install --global --ignore-scripts frely-cli@latest
 ```
 
-安装器会选择对应平台的可执行文件，校验 SHA-256，安装到用户目录，不需要 Node.js。下载先走 GitHub Releases，GitHub 过慢或连不上时改用 npmmirror 和 npmjs（`@frelyhq/cli-<平台>`）。`FRELY_INSTALL_SOURCES` 可调整顺序。
+安装器会校验 SHA-256，下载先走 GitHub Releases，再回退到 npmmirror 和 npmjs。[详情](https://cli.frely.cloud/docs/help/install-only/)
 
 ## 常用命令
 
 | 命令 | 作用 |
 | --- | --- |
-| `frely mcp start` | 需要时先登录，开启设备 MCP，启动服务并输出 MCP URL。可重复运行。 |
+| `frely mcp start` | 需要时登录，开启设备 MCP，启动服务并输出 MCP URL。可重复运行。 |
 | `frely mcp status` | 显示 MCP URL、工作区、授权到期时间和服务状态。 |
-| `frely mcp workspace add <path>` | 再共享一个文件夹。`frely mcp workspace list` 列出全部。 |
+| `frely mcp workspace add <path>` | 共享另一个文件夹。`frely mcp workspace list` 列出全部。 |
 | `frely mcp stop` / `frely mcp start` | 暂停或恢复后台服务。 |
 | `frely mcp remove` | 撤销所有客户端的访问并卸载服务。 |
-| `frely doctor` | 检查登录、安装、服务和连接状态。加 `-v` 看详情。 |
-| `frely update` | 原地升级到最新版。 |
+| `frely doctor` | 检查登录、安装、服务和连接。`-v` 显示详情。 |
+| `frely update` | 原地升级到最新版本。 |
 | `frely login` / `frely logout` | 登录或退出 Frely 账号。 |
+| `frely sandbox proxy <url>` | 让命令沙箱的网络流量转发到你自己的 HTTP(S) 代理。未设置时使用 CLI 进程的 `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY`，macOS 上还会读系统代理。`--clear` 删除；重启服务后生效。 |
+| `frely tunnel <host>:<port>` | 在沙箱命令内使用：监听 `127.0.0.1`，把 TCP 连接经沙箱转发到 `host:port`，供数据库、redis 客户端使用。`--local-port N` 指定本地端口。 |
 | `frely uninstall` | 从这台电脑移除 Frely（先列出全部内容）。 |
 
-只输入命令组而不带子命令（如 `frely mcp`、`frely agent`）会列出该组的子命令。
+全部命令和参数见[命令参考](https://cli.frely.cloud/docs/help/commands/)。`frely help --agent --json` 输出完整的机器可读契约。
 
 ## 与 FrelyMCP 配合使用
 
-FrelyMCP 是整个账号共用的一个 MCP 地址：`https://mcp.frely.cloud/mcp`。每台运行过 `frely mcp start` 的电脑都在它后面。`frely-cli` 在各台电脑上执行工具，AI 客户端只需要这个 URL。
+FrelyMCP 是整个账号共用的一个 MCP 地址：`https://mcp.frely.cloud/mcp`。每台运行过 `frely mcp start` 的电脑都在它后面。
 
-### 连接客户端
-
-1. 在要被控制的电脑上运行 `frely mcp start`（上面的安装脚本已经包含这一步），它会输出 MCP URL。
+1. 在要被控制的电脑上运行 `frely mcp start`（上面的安装脚本已经包含这一步）。
 2. 把 URL 作为使用 OAuth 的远程 MCP 服务加到客户端：
    - ChatGPT 或 Claude：用这个 URL 添加自定义连接器。
    - 另一台电脑上的 Claude Code：`claude mcp add --transport http frely "https://mcp.frely.cloud/mcp"`，然后打开 `/mcp` 完成授权。
 3. 登录 Frely 并批准该客户端。
 
-验证连接：让客户端列出工作区的顶层文件名，结果与文件夹一致即表示连通。
-
-### AI 能做什么
-
-- `list_devices` 列出你的电脑、是否在线及其工作区。没有电脑时，它会给出上面的安装命令。
-- 设备工具带 `device` 参数，在那台电脑上执行：
-  - `read`：在工作区内列出、读取、搜索和查找文件。
-  - `edit_file`：原子地写入整个文件或按行修改。
-  - `process`：运行 Shell 命令，或启动和管理长时间运行的进程。
-  - `web_fetch`：读取公开网页。
-- `local_mcp_list` 和 `local_mcp_call` 访问那台电脑上你已开启的 MCP 服务（见下文）。
-- `frely_list` 和 `frely_call` 管理你的 Frely 账号（API Key、Credit、套餐、订单）。终端里的 `frely api list|describe|call` 是同一套操作。
-
-AI 客户端自带的 Shell 仍在客户端所在的电脑上运行；要在你的电脑上工作，请让它使用 Frely 工具。所有客户端共享每台电脑的工作区和正在运行的进程。
-
-### 本机 MCP 服务
+验证连接：让客户端列出工作区的顶层文件名。
 
-只监听本机回环地址的服务会被自动发现（`frely mcp local list`）。其他服务这样添加：
-
-```sh
-frely mcp local add <name> --url http://127.0.0.1:<port>/mcp
-frely mcp local add <name> [--env KEY=VALUE] -- <command> [args...]   # stdio
-```
-
-每个服务默认对远程客户端隐藏，需要在 Frely 连接页面逐个开启。开启后的服务在命令沙箱之外、以你的用户身份运行。只会连接回环地址，headers 和环境变量不会离开这台电脑。
-
-### 授权
-
-设备 MCP 授权默认 90 天；`frely mcp start --days 1..365` 可提前续期。到期后 `frely mcp start` 会再次请求批准。URL 永远不变。在 Frely 网站的 **My Devices** 管理你的电脑。
+- **AI 能做什么**：先 `list_devices`，再在选定的电脑上用 `read`、`edit_file`、`process`、`web_fetch`，账号操作用 `frely_list` 和 `frely_call`。[详情](https://cli.frely.cloud/docs/help/what-can-the-ai-do/)
+- **本机 MCP 服务**：只监听回环地址的服务会被自动发现（`frely mcp local list`），每个都要在 Frely 上逐个开启才对远程可见。[详情](https://cli.frely.cloud/docs/help/local-mcp-servers/)
+- **授权**：默认 90 天，`frely mcp start --days 1..365` 可提前续期，URL 永远不变。[详情](https://cli.frely.cloud/docs/help/authorization-expiry/)
 
 ## 更多功能
 
-### 调用 Frely 托管的 Agent
-
-```sh
-frely agent install <distribution-id> --host claude-code --scope global
-printf '%s' 'Your complete task' | frely agent run <distribution-id> --input-stdin --json
-```
-
-`--host` 可选 `chatgpt`、`codex`、`claude-code`、`pi` 或 `generic`。也可以用完整的 manifest URL 代替 id。要用 Creator 提供的赞助 API Key 而不是你的账号，用 `--api-key-stdin` 从 stdin 传入；Key 存入安全凭据库，不会写进 Skill。请使用短期、单模型、限额的 Key。`frely agent status <id>` 显示 Skill 和 Key 的额度；`frely agent remove <id>` 同时移除两者。
+- **Frely 托管的 Agent**：`frely agent install <distribution-id> --host claude-code` 安装为本地 Skill，`frely agent run` 调用。[详情](https://cli.frely.cloud/docs/help/install-agents-and-items/)
+- **市场里的 Prompt 和 Skill**：`frely item install <item-id> --host claude-code`，付费部分需要账号持有通行证。[详情](https://cli.frely.cloud/docs/help/install-agents-and-items/)
+- **本地模型共享**：`frely provider share ollama` 把本机模型服务发布为你的个人 Frely Provider。[详情](https://cli.frely.cloud/docs/help/share-local-model/)
+- **在终端管理账号**：`frely api list|describe|call`。[详情](https://cli.frely.cloud/docs/help/manage-account-from-cli/)
 
-### 安装市场里的 Prompt 和 Skill
-
-```sh
-frely item install <item-id> --host claude-code
-```
-
-首次调用会打开浏览器进行 Frely Cloud 授权。账号持有通行证时才安装付费部分，否则命令会告诉你如何购买。Skill 装到宿主的 Skill 目录，Prompt 装到 `--dir`（默认当前目录），脚本保存时不带执行权限。Frely 不会覆盖不是它安装的文件夹，也不会覆盖你改过的文件。审查过已安装的条目后，`frely item trust <folder>` 会记住；新版本需要重新审查。
-
-你购买的云端 MCP 不会安装到电脑上：在 Frely 网站为某个连接开启后，它们的工具会出现在 FrelyMCP 里。
-
-### 本地模型共享
-
-```sh
-frely provider share ollama
-frely provider share openai-compatible --url http://127.0.0.1:8080/v1 --models model-a,model-b --name "Local GPU"
-frely provider list
-```
-
-把本机回环地址上的 OpenAI 兼容端点（默认 Ollama `http://127.0.0.1:11434/v1`）发布为 Frely 个人 Provider，占用一个空的个人 Provider 名额。没有空名额或使用 `--creator` 时，会创建 Creator Provider，计入你的 Creator 套餐，其模型可作为你发布的 Agent 的底座。使用期间请保持电脑在线，并确保运行时在响应中返回 `usage`。设置中途停止时，再次运行同一命令即可继续。
-
-## 本地执行边界
-
-- **文件**：文件工具只在共享的工作区内操作，拒绝符号链接逃逸，单次读写上限 1 MiB，写入是原子的。即使在主目录内，凭据库和 Shell 启动文件也受保护。
-- **命令**：`process` 以你的系统用户身份在系统级沙箱中运行。凭据目录不可读，写入限于工作区和临时目录，网络经代理。电脑无法使用沙箱时（Windows，或 Linux 缺少 `bubblewrap`、`socat`、`ripgrep`），命令会被拒绝而不是在沙箱外运行。可以在 Frely 连接页面开放更多：可读的凭据目录、可写的其他目录，或限时无沙箱运行。在设备上设置 `FRELY_SANDBOX=off` 可关闭沙箱。
-- **凭据**：MCP URL 不含任何密钥。客户端持有 OAuth 令牌；CLI 持有独立的 MCP 执行密钥，用 macOS 钥匙串、Windows 凭据管理器或 Linux Secret Service 中的主密钥加密。无界面的机器可设置 `FRELY_CREDENTIAL_KEY`（32 字节）并配合 `FRELY_CREDENTIAL_STORE=encrypted-file`。授权到期后，请求和排队的工作会停止；已完成的写入不会撤销。
-
-详情：[凭据与安装边界](docs/credential-storage.md)。
-
-## 升级、诊断与卸载
-
-```sh
-frely doctor      # 账号、安装、最新版本、MCP 与服务状态
-frely doctor -v   # 另含配置路径、授权到期、最后心跳、脱敏错误
-frely update      # 原地升级，保留登录、设备、URL 和工作区
-frely uninstall   # 先列出全部内容，输入 yes 后移除（脚本用 --yes）
-```
-
-`frely update` 保持原有安装方式，不会降级。它暂停后台服务，校验后替换程序，再重启服务。Windows 上它会输出一条 PowerShell 命令，请在本地终端运行。见[自更新](docs/self-update.md)和[服务维护](docs/service-maintenance.md)。
-
-`frely uninstall` 在 Frely 端撤销这台电脑的访问，移除服务、保存的登录、设备身份、设置、缓存和 Frely 安装的 Agent Skill，最后移除 `frely` 程序本身。它会保留 Frely App、账号里的 Provider 和 Agent、安装器添加的 PATH 行、你改过的 Skill 和市场条目。请在本地终端运行，不要通过设备 MCP 运行。
-
-## 全部命令
-
-```text
-frely login [--relay <https-url>] [--no-browser]
-frely login --email <address> [--mcp] [--workspace <path>]   then   frely login --code <6-digit code>
-frely logout
-frely uninstall [--yes] [--json]
-frely doctor [-v] [--json]
-frely update
-frely mcp start [--workspace <path>] [--days 1..365] [--no-browser] [--json]
-frely mcp status [--json]
-frely mcp stop|remove
-frely mcp workspace list [--json]
-frely mcp workspace add|remove <path>
-frely mcp local list [--json]
-frely mcp local add <name> (--url <address> | [--env KEY=VALUE] -- <command> [args...])
-frely mcp local remove <name>
-frely agent install <distribution-id|manifest-url> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--api-key-stdin] [--json]
-frely agent run <distribution-id> (--input <text>|--input-stdin) [--json]
-frely agent status (<distribution-id>|--api-key-stdin [--relay <url>]) [--json]
-frely agent remove <distribution-id> [--json]
-frely item install <item-id> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--dir <path>] [--json]
-frely item trust <folder> [--check]
-frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id> | --creator] [--name <name>]
-frely provider list [--json]
-frely api list|describe|call
-```
+## 安全
 
-`frely help --agent --json` 输出完整的机器可读契约，包括 `frely --help` 中未列出的命令：`frely mcp stdio`（通过 stdio 向本地客户端提供工具）、`frely mcp serve`（后台服务运行的前台进程）和 `frely network`（预览）。
+文件工具只在共享的工作区内工作，凭据和 Shell 启动文件受保护。命令以你的系统用户身份在系统沙箱中运行，无法沙箱时直接拒绝。客户端持有 OAuth 令牌，CLI 的密钥保存在系统凭据库中。[安全吗？](https://cli.frely.cloud/docs/help/is-it-safe/) · [沙箱与权限](https://cli.frely.cloud/docs/help/sandbox-and-permissions/) · [凭据存储](docs/credential-storage.md)
 
 ## 文档
 
-- [设备 MCP](docs/device-mcp.md)
-- [Device Relay 传输](docs/device-transport.md)
-- [MCP OAuth 契约](docs/mcp-oauth-relay-contract.md)
-- [`frely api`](docs/api.md)
-- [Frely Network（预览）](docs/frely-network.md)
+- 帮助：[cli.frely.cloud/docs](https://cli.frely.cloud/docs/)（[升级](https://cli.frely.cloud/docs/help/update/)、[诊断](https://cli.frely.cloud/docs/help/doctor/)、[卸载](https://cli.frely.cloud/docs/help/uninstall/)）
+- 契约（面向贡献者）：[设备 MCP](docs/device-mcp.md) · [Device Relay 传输](docs/device-transport.md) · [MCP OAuth 契约](docs/mcp-oauth-relay-contract.md) · [`frely api`](docs/api.md) · [Frely Network（预览）](docs/frely-network.md) · [自升级](docs/self-update.md) · [服务维护](docs/service-maintenance.md)
 
 ## 许可与商标
 

package/dist/agent-help.d.ts

@@ -88,6 +88,12 @@ export declare const COMMANDS: readonly [{
     readonly auth: "none";
     readonly effect: "local-service";
     readonly purpose: "Stop the local MCP background service without revoking authorization; frely mcp start resumes it. Supported updates restore running services without this command.";
+}, {
+    readonly id: "mcp.auto-update";
+    readonly usage: "frely mcp auto-update [on|off]";
+    readonly auth: "none";
+    readonly effect: "local-write";
+    readonly purpose: "Show or set whether this device's background service installs new stable versions of its own installation while idle and restarts itself. Off by default; macOS and Linux only.";
 }, {
     readonly id: "mcp.remove";
     readonly usage: "frely mcp remove";
@@ -166,6 +172,18 @@ export declare const COMMANDS: readonly [{
     readonly auth: "account";
     readonly effect: "read";
     readonly purpose: "List configured local Providers.";
+}, {
+    readonly id: "tunnel";
+    readonly usage: "frely tunnel <host>:<port> [--local-port N]";
+    readonly auth: "none";
+    readonly effect: "local-execution";
+    readonly purpose: "Run inside a sandboxed command (run_command): listen on 127.0.0.1:<local-port> (default: the same port) and forward each TCP connection to host:port through the command sandbox's proxy, so database and redis clients connect to 127.0.0.1 without turning the sandbox off. Start it in the same command as the client, for example `frely tunnel db.example.com:5432 & sleep 1; psql -h 127.0.0.1 ...`. Prints the local address and runs until killed.";
+}, {
+    readonly id: "sandbox.proxy";
+    readonly usage: "frely sandbox proxy [<http://host:port> [--no-proxy <list>] | --clear]";
+    readonly auth: "none";
+    readonly effect: "local-write";
+    readonly purpose: "Show, save or remove the HTTP(S) proxy that the command sandbox forwards its network traffic to (your own proxy, for example Clash). Without one saved it uses the HTTPS_PROXY / HTTP_PROXY / ALL_PROXY of the CLI process and, on macOS, the system proxy. Your proxy settings are never changed. Takes effect when the MCP service restarts.";
 }, {
     readonly id: "api";
     readonly usage: "frely api list|describe|call [--help]";
@@ -208,6 +226,12 @@ export declare const COMMANDS: readonly [{
     readonly auth: "local";
     readonly effect: "local-write";
     readonly purpose: "Lift the local block set by `frely computer disable` and pre-install the computer-use runtime. Computer use (desktop control by a remote MCP client) is built in and stays off until the owner turns it on for the device on the Frely connections page (passkey or authenticator code required). On macOS the first use asks that Mac for Accessibility and Screen Recording permission.";
+}, {
+    readonly id: "computer.doctor";
+    readonly usage: "frely computer doctor";
+    readonly auth: "local";
+    readonly effect: "local-execution";
+    readonly purpose: "Check and request the OS permissions computer use needs (macOS Accessibility and Screen Recording; Windows as applicable) by running the installed runtime's doctor. `frely computer enable` runs it automatically, and a computer-use call that fails for missing permission starts it too.";
 }, {
     readonly id: "computer.disable";
     readonly usage: "frely computer disable";
@@ -329,6 +353,12 @@ export declare function agentHelp(): {
         readonly auth: "none";
         readonly effect: "local-service";
         readonly purpose: "Stop the local MCP background service without revoking authorization; frely mcp start resumes it. Supported updates restore running services without this command.";
+    }, {
+        readonly id: "mcp.auto-update";
+        readonly usage: "frely mcp auto-update [on|off]";
+        readonly auth: "none";
+        readonly effect: "local-write";
+        readonly purpose: "Show or set whether this device's background service installs new stable versions of its own installation while idle and restarts itself. Off by default; macOS and Linux only.";
     }, {
         readonly id: "mcp.remove";
         readonly usage: "frely mcp remove";
@@ -407,6 +437,18 @@ export declare function agentHelp(): {
         readonly auth: "account";
         readonly effect: "read";
         readonly purpose: "List configured local Providers.";
+    }, {
+        readonly id: "tunnel";
+        readonly usage: "frely tunnel <host>:<port> [--local-port N]";
+        readonly auth: "none";
+        readonly effect: "local-execution";
+        readonly purpose: "Run inside a sandboxed command (run_command): listen on 127.0.0.1:<local-port> (default: the same port) and forward each TCP connection to host:port through the command sandbox's proxy, so database and redis clients connect to 127.0.0.1 without turning the sandbox off. Start it in the same command as the client, for example `frely tunnel db.example.com:5432 & sleep 1; psql -h 127.0.0.1 ...`. Prints the local address and runs until killed.";
+    }, {
+        readonly id: "sandbox.proxy";
+        readonly usage: "frely sandbox proxy [<http://host:port> [--no-proxy <list>] | --clear]";
+        readonly auth: "none";
+        readonly effect: "local-write";
+        readonly purpose: "Show, save or remove the HTTP(S) proxy that the command sandbox forwards its network traffic to (your own proxy, for example Clash). Without one saved it uses the HTTPS_PROXY / HTTP_PROXY / ALL_PROXY of the CLI process and, on macOS, the system proxy. Your proxy settings are never changed. Takes effect when the MCP service restarts.";
     }, {
         readonly id: "api";
         readonly usage: "frely api list|describe|call [--help]";
@@ -449,6 +491,12 @@ export declare function agentHelp(): {
         readonly auth: "local";
         readonly effect: "local-write";
         readonly purpose: "Lift the local block set by `frely computer disable` and pre-install the computer-use runtime. Computer use (desktop control by a remote MCP client) is built in and stays off until the owner turns it on for the device on the Frely connections page (passkey or authenticator code required). On macOS the first use asks that Mac for Accessibility and Screen Recording permission.";
+    }, {
+        readonly id: "computer.doctor";
+        readonly usage: "frely computer doctor";
+        readonly auth: "local";
+        readonly effect: "local-execution";
+        readonly purpose: "Check and request the OS permissions computer use needs (macOS Accessibility and Screen Recording; Windows as applicable) by running the installed runtime's doctor. `frely computer enable` runs it automatically, and a computer-use call that fails for missing permission starts it too.";
     }, {
         readonly id: "computer.disable";
         readonly usage: "frely computer disable";