frely-cli 0.23.8 → 0.23.10

package/dist/agent-help.d.ts

@@ -1,9 +1,9 @@
 export declare const COMMANDS: readonly [{
     readonly id: "login";
-    readonly usage: "frely login [--relay <url>] [--no-browser] | frely login --email <address> [--invite <link>] [--mcp] [--workspace <path>] [--days <n>] then frely login --code <6-digit code>";
+    readonly usage: "frely login [--relay <url>] [--no-browser] | frely login --wait | frely login --email <address> [--invite <link>] [--mcp] [--workspace <path>] [--days <n>] then frely login --code <6-digit code>";
     readonly auth: "browser-or-email";
     readonly effect: "authorization";
-    readonly purpose: "Authorize the CLI for the user's Frely account. With --email, Frely emails a code; the user pastes it into `frely login --code` (enter only the 6 digits; the mail also shows a short reference such as K7, which is only for matching the mail). Add --mcp to also enable device MCP for the workspace (default 90 days) once the code is verified; do this when the user is registering for the first time, and tell them before asking for the code.";
+    readonly purpose: "Authorize the CLI for the user's Frely account. The browser form blocks until the user approves, then returns, so continue the task when it exits; if the command is stopped first, run `frely login --wait` to resume on the same link. With --email, Frely emails a code; the user pastes it into `frely login --code` (enter only the 6 digits; the mail also shows a short reference such as K7, which is only for matching the mail). Add --mcp to also enable device MCP for the workspace (default 90 days) once the code is verified; do this when the user is registering for the first time, and tell them before asking for the code.";
 }, {
     readonly id: "logout";
     readonly usage: "frely logout";
@@ -144,19 +144,19 @@ export declare const COMMANDS: readonly [{
     readonly purpose: "Install a download-install Prompt or Skill from the marketplace through Frely Cloud. The paid part is installed only with a valid pass; otherwise the command prints how to buy one. Skills go to the host Skill folder, Prompts to --dir (default: current directory). Scripts are saved without execute permission.";
 }, {
     readonly id: "remote.tools";
-    readonly usage: "frely remote tools <username/name> [--json]";
+    readonly usage: "frely remote tools <username/name> [--json] [--replace]";
     readonly auth: "cloud-oauth";
     readonly effect: "remote-read";
-    readonly purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP.";
+    readonly purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP. If the name now belongs to a different MCP than the one connected before, it stops; --replace switches to the new one.";
 }, {
     readonly id: "remote.call";
-    readonly usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>]";
+    readonly usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>] [--replace]";
     readonly auth: "cloud-oauth";
     readonly effect: "remote-call";
     readonly purpose: "Call one tool of a remote MCP product and print the result as JSON (exit code 1 when the tool reports an error). Each call is billed or needs a pass exactly as in an MCP client; ask the user before a call that writes data they did not ask for.";
 }, {
     readonly id: "remote.config";
-    readonly usage: "frely remote config <username/name> [--write <file>]";
+    readonly usage: "frely remote config <username/name> [--write <file>] [--replace]";
     readonly auth: "cloud-oauth";
     readonly effect: "remote-write";
     readonly purpose: "Get a new key for one remote MCP product (it replaces the previous one) and print the mcpServers JSON that MCP clients take for it; with --write the entry is merged into that JSON file (created 0600) instead of printed. The key works only for this MCP.";
@@ -184,18 +184,78 @@ export declare const COMMANDS: readonly [{
     readonly auth: "none";
     readonly effect: "local-write";
     readonly purpose: "Remove an installed Agent Skill and its saved API key.";
+}, {
+    readonly id: "agent.local.add";
+    readonly usage: "frely agent local add <username/name | https://github.com/owner/repo> [--name <folder-name>]";
+    readonly auth: "optional-account";
+    readonly effect: "local-write";
+    readonly purpose: "Download an Agent's repository into its own folder under ~/frely-agents and run its setup inside the sandbox. The sandbox can write only that folder, cannot read credential folders and can reach only Frely's API plus the sites the repository lists in frely.yaml, each of which the owner approves once through a link (exit code 3 with the link when nobody can wait; approve, then run the same command again). Needs a frely.yaml with a local.run command.";
+}, {
+    readonly id: "agent.local.start";
+    readonly usage: "frely agent local start <name> [--foreground]";
+    readonly auth: "account-and-api-key";
+    readonly effect: "local-process";
+    readonly purpose: "Run a local Agent in the background inside the sandbox. Its model calls go through a local proxy that adds the Frely API key (saved with `frely agent local key`), so the repository's code never sees it. Billed to the key like any other API call.";
+}, {
+    readonly id: "agent.local.stop";
+    readonly usage: "frely agent local stop <name>";
+    readonly auth: "none";
+    readonly effect: "local-process";
+    readonly purpose: "Stop a running local Agent. Run start again afterwards to apply newly approved sites.";
+}, {
+    readonly id: "agent.local.logs";
+    readonly usage: "frely agent local logs <name> [--lines <n>] [--follow]";
+    readonly auth: "none";
+    readonly effect: "read";
+    readonly purpose: "Show what a local Agent printed, including what the sandbox blocked.";
+}, {
+    readonly id: "agent.local.list";
+    readonly usage: "frely agent local list [--json]";
+    readonly auth: "none";
+    readonly effect: "read";
+    readonly purpose: "List the Agents on this computer, whether each is running, and the sites each has been approved for.";
+}, {
+    readonly id: "agent.local.remove";
+    readonly usage: "frely agent local remove <name>";
+    readonly auth: "none";
+    readonly effect: "local-write";
+    readonly purpose: "Stop a local Agent and delete its folder and records. Only the Agent's own folder is removed.";
+}, {
+    readonly id: "agent.local.key";
+    readonly usage: "frely agent local key --api-key-stdin | --clear";
+    readonly auth: "account";
+    readonly effect: "local-write";
+    readonly purpose: "Save the Frely API key that local Agents use for model calls; it goes only through stdin to secure storage. FRELY_API_KEY overrides it.";
 }, {
     readonly id: "provider.share";
     readonly usage: "frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]";
     readonly auth: "account";
     readonly effect: "remote-write";
-    readonly purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead.";
+    readonly purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance.";
 }, {
     readonly id: "provider.list";
     readonly usage: "frely provider list [--json]";
     readonly auth: "account";
     readonly effect: "read";
     readonly purpose: "List configured local Providers.";
+}, {
+    readonly id: "share";
+    readonly usage: "frely share <port> [--ttl <hours>] [--rewrite-host] [--yes] [--json]";
+    readonly auth: "account";
+    readonly effect: "remote-write";
+    readonly purpose: "Make a web service on this computer (http://127.0.0.1:<port>) reachable from the Internet by a private link through Frely's relay, until Ctrl+C or expiry (at most 24 hours). Asks first. The relay allowance is a plan limit per UTC week; --rewrite-host sends Host: localhost to dev servers that refuse other names. Not the same as `frely provider share` (local models) or `frely tunnel` (command sandbox).";
+}, {
+    readonly id: "service.share";
+    readonly usage: "frely service share --type mcp|a2a --port <n> [--label <text>] [--background] [--json]";
+    readonly auth: "account";
+    readonly effect: "remote-write";
+    readonly purpose: "Connect an MCP server or A2A Agent that runs on this computer (127.0.0.1:<port>) to Frely so you can sell it, without a public address: only Frely's own cloud can reach it, the port never leaves this computer, and Frely never supplies a target. Runs until Ctrl+C, or with --background the device background service keeps it connected. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance.";
+}, {
+    readonly id: "service.manage";
+    readonly usage: "frely service list [--json] | stop <id|label> | remove <id|label>";
+    readonly auth: "account";
+    readonly effect: "remote-write";
+    readonly purpose: "List registered services, stop one on this computer (it stays registered), or remove it from Frely (products that pointed at it become unreachable).";
 }, {
     readonly id: "tunnel";
     readonly usage: "frely tunnel <host>:<port> [--local-port N]";
@@ -208,12 +268,90 @@ export declare const COMMANDS: readonly [{
     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: "devices";
+    readonly usage: "frely devices [--add] [--json]";
+    readonly auth: "controller";
+    readonly effect: "read";
+    readonly purpose: "List your Frely devices with online state and workspaces (list_devices). --add prints a one-time install command for a new computer.";
+}, {
+    readonly id: "run";
+    readonly usage: "frely run <device> [--cwd <dir>] [--timeout <s>] [--background] -- <command> [--json] [--out <file>]";
+    readonly auth: "controller";
+    readonly effect: "remote-execution";
+    readonly purpose: "Run a shell command on a device inside its sandbox and print its output; --background returns a process id. The command's own failure is exit code 2.";
+}, {
+    readonly id: "ps";
+    readonly usage: "frely ps <device>";
+    readonly auth: "controller";
+    readonly effect: "read";
+    readonly purpose: "List background commands on a device.";
+}, {
+    readonly id: "logs";
+    readonly usage: "frely logs <device> <id> [--follow]";
+    readonly auth: "controller";
+    readonly effect: "read";
+    readonly purpose: "Output of a background command; --follow shows it live until it ends.";
+}, {
+    readonly id: "kill";
+    readonly usage: "frely kill <device> <id>";
+    readonly auth: "controller";
+    readonly effect: "remote-execution";
+    readonly purpose: "Stop a background command on a device.";
+}, {
+    readonly id: "read";
+    readonly usage: "frely read <device>:<path> [--lines a:b] [--json] [--out <file>]";
+    readonly auth: "controller";
+    readonly effect: "read";
+    readonly purpose: "Print a file on a device (UTF-8, up to 1 MiB). A Windows drive path such as C:\\x is this computer, not a device.";
+}, {
+    readonly id: "ls";
+    readonly usage: "frely ls [<device>[:<path>]] [--json]";
+    readonly auth: "controller";
+    readonly effect: "read";
+    readonly purpose: "List a folder on a device; with only a device, its workspace roots.";
+}, {
+    readonly id: "grep";
+    readonly usage: "frely grep <device>:<path> <text> [--regex] [--case] [--max <n>]";
+    readonly auth: "controller";
+    readonly effect: "read";
+    readonly purpose: "Search file contents on a device.";
+}, {
+    readonly id: "edit";
+    readonly usage: "frely edit <device>:<path> (--from <local file> | --patch <json file>) [--overwrite]";
+    readonly auth: "controller";
+    readonly effect: "remote-write";
+    readonly purpose: "Write a device file from a local file, or apply line-range edits from a JSON file.";
+}, {
+    readonly id: "permission";
+    readonly usage: "frely permission request <device> --resource <name> --reason <text> --command <text> | confirm <code> [A|B|C] | wait <short code> [--then '<command>']";
+    readonly auth: "controller";
+    readonly effect: "authorization";
+    readonly purpose: "Ask the owner to open what the device sandbox blocks. Exit code 3 prints the approval link and the wait command: show the link to the user, then run `frely permission wait <short code> --then '<original command>'` in the background so the original command runs once they approve.";
+}, {
+    readonly id: "tools";
+    readonly usage: "frely tools [--json]";
+    readonly auth: "controller";
+    readonly effect: "read";
+    readonly purpose: "Print FrelyMCP's own instructions and every tool it offers.";
+}, {
+    readonly id: "call";
+    readonly usage: "frely call <tool> [--json '<object>' | --input <file>] [--out <file>]";
+    readonly auth: "controller";
+    readonly effect: "subcommand-dependent";
+    readonly purpose: "Call any FrelyMCP tool by name (browser, models, web_fetch, local_mcp_call, store, ...).";
+}, {
+    readonly id: "controller";
+    readonly usage: "frely controller login|logout|status";
+    readonly auth: "browser";
+    readonly effect: "authorization-if-needed";
+    readonly purpose: "Authorize this computer to control your devices: shows a short code, you open the link, type the code and confirm with a passkey or authenticator code. The first controller command does this by itself in a terminal.";
 }, {
     readonly id: "api";
     readonly usage: "frely api list|describe|call [--wait] [--help]";
-    readonly auth: "cloud-oauth";
+    readonly auth: "controller";
     readonly effect: "subcommand-dependent";
-    readonly purpose: "Discover and call your Frely account's business operations (the same tools FrelyMCP offers through frely_list/frely_call). The first call requests browser authorization. `list` is grouped and compact (add --json for the full tool list); use describe before call; parameters and results are JSON; --input reads a file up to 512 KiB. When a call needs the owner's approval the error links to it; run the call with --wait (in the foreground, tool timeout of at least 10 minutes) to show the user the link first and then block until they approve on their phone or the web, so the call finishes by itself and you need not be told. Never background or kill it.";
+    readonly purpose: "Discover and call your Frely account's business operations (the same tools FrelyMCP offers through frely_list/frely_call). Runs on this computer's controller authorization; the first call requests browser approval (frely controller login). `list` is grouped and compact (add --json for the full tool list); use describe before call; parameters and results are JSON; --input reads a file up to 512 KiB. When a call needs the owner's approval the error links to it; run the call with --wait (in the foreground, tool timeout of at least 10 minutes) to show the user the link first and then block until they approve on their phone or the web, so the call finishes by itself and you need not be told. Never background or kill it.";
 }, {
     readonly id: "app.install";
     readonly usage: "frely app install [--force] [--json]";
@@ -289,10 +427,10 @@ export declare function agentHelp(): {
     instructions: string[];
     commands: readonly [{
         readonly id: "login";
-        readonly usage: "frely login [--relay <url>] [--no-browser] | frely login --email <address> [--invite <link>] [--mcp] [--workspace <path>] [--days <n>] then frely login --code <6-digit code>";
+        readonly usage: "frely login [--relay <url>] [--no-browser] | frely login --wait | frely login --email <address> [--invite <link>] [--mcp] [--workspace <path>] [--days <n>] then frely login --code <6-digit code>";
         readonly auth: "browser-or-email";
         readonly effect: "authorization";
-        readonly purpose: "Authorize the CLI for the user's Frely account. With --email, Frely emails a code; the user pastes it into `frely login --code` (enter only the 6 digits; the mail also shows a short reference such as K7, which is only for matching the mail). Add --mcp to also enable device MCP for the workspace (default 90 days) once the code is verified; do this when the user is registering for the first time, and tell them before asking for the code.";
+        readonly purpose: "Authorize the CLI for the user's Frely account. The browser form blocks until the user approves, then returns, so continue the task when it exits; if the command is stopped first, run `frely login --wait` to resume on the same link. With --email, Frely emails a code; the user pastes it into `frely login --code` (enter only the 6 digits; the mail also shows a short reference such as K7, which is only for matching the mail). Add --mcp to also enable device MCP for the workspace (default 90 days) once the code is verified; do this when the user is registering for the first time, and tell them before asking for the code.";
     }, {
         readonly id: "logout";
         readonly usage: "frely logout";
@@ -433,19 +571,19 @@ export declare function agentHelp(): {
         readonly purpose: "Install a download-install Prompt or Skill from the marketplace through Frely Cloud. The paid part is installed only with a valid pass; otherwise the command prints how to buy one. Skills go to the host Skill folder, Prompts to --dir (default: current directory). Scripts are saved without execute permission.";
     }, {
         readonly id: "remote.tools";
-        readonly usage: "frely remote tools <username/name> [--json]";
+        readonly usage: "frely remote tools <username/name> [--json] [--replace]";
         readonly auth: "cloud-oauth";
         readonly effect: "remote-read";
-        readonly purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP.";
+        readonly purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP. If the name now belongs to a different MCP than the one connected before, it stops; --replace switches to the new one.";
     }, {
         readonly id: "remote.call";
-        readonly usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>]";
+        readonly usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>] [--replace]";
         readonly auth: "cloud-oauth";
         readonly effect: "remote-call";
         readonly purpose: "Call one tool of a remote MCP product and print the result as JSON (exit code 1 when the tool reports an error). Each call is billed or needs a pass exactly as in an MCP client; ask the user before a call that writes data they did not ask for.";
     }, {
         readonly id: "remote.config";
-        readonly usage: "frely remote config <username/name> [--write <file>]";
+        readonly usage: "frely remote config <username/name> [--write <file>] [--replace]";
         readonly auth: "cloud-oauth";
         readonly effect: "remote-write";
         readonly purpose: "Get a new key for one remote MCP product (it replaces the previous one) and print the mcpServers JSON that MCP clients take for it; with --write the entry is merged into that JSON file (created 0600) instead of printed. The key works only for this MCP.";
@@ -473,18 +611,78 @@ export declare function agentHelp(): {
         readonly auth: "none";
         readonly effect: "local-write";
         readonly purpose: "Remove an installed Agent Skill and its saved API key.";
+    }, {
+        readonly id: "agent.local.add";
+        readonly usage: "frely agent local add <username/name | https://github.com/owner/repo> [--name <folder-name>]";
+        readonly auth: "optional-account";
+        readonly effect: "local-write";
+        readonly purpose: "Download an Agent's repository into its own folder under ~/frely-agents and run its setup inside the sandbox. The sandbox can write only that folder, cannot read credential folders and can reach only Frely's API plus the sites the repository lists in frely.yaml, each of which the owner approves once through a link (exit code 3 with the link when nobody can wait; approve, then run the same command again). Needs a frely.yaml with a local.run command.";
+    }, {
+        readonly id: "agent.local.start";
+        readonly usage: "frely agent local start <name> [--foreground]";
+        readonly auth: "account-and-api-key";
+        readonly effect: "local-process";
+        readonly purpose: "Run a local Agent in the background inside the sandbox. Its model calls go through a local proxy that adds the Frely API key (saved with `frely agent local key`), so the repository's code never sees it. Billed to the key like any other API call.";
+    }, {
+        readonly id: "agent.local.stop";
+        readonly usage: "frely agent local stop <name>";
+        readonly auth: "none";
+        readonly effect: "local-process";
+        readonly purpose: "Stop a running local Agent. Run start again afterwards to apply newly approved sites.";
+    }, {
+        readonly id: "agent.local.logs";
+        readonly usage: "frely agent local logs <name> [--lines <n>] [--follow]";
+        readonly auth: "none";
+        readonly effect: "read";
+        readonly purpose: "Show what a local Agent printed, including what the sandbox blocked.";
+    }, {
+        readonly id: "agent.local.list";
+        readonly usage: "frely agent local list [--json]";
+        readonly auth: "none";
+        readonly effect: "read";
+        readonly purpose: "List the Agents on this computer, whether each is running, and the sites each has been approved for.";
+    }, {
+        readonly id: "agent.local.remove";
+        readonly usage: "frely agent local remove <name>";
+        readonly auth: "none";
+        readonly effect: "local-write";
+        readonly purpose: "Stop a local Agent and delete its folder and records. Only the Agent's own folder is removed.";
+    }, {
+        readonly id: "agent.local.key";
+        readonly usage: "frely agent local key --api-key-stdin | --clear";
+        readonly auth: "account";
+        readonly effect: "local-write";
+        readonly purpose: "Save the Frely API key that local Agents use for model calls; it goes only through stdin to secure storage. FRELY_API_KEY overrides it.";
     }, {
         readonly id: "provider.share";
         readonly usage: "frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]";
         readonly auth: "account";
         readonly effect: "remote-write";
-        readonly purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead.";
+        readonly purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance.";
     }, {
         readonly id: "provider.list";
         readonly usage: "frely provider list [--json]";
         readonly auth: "account";
         readonly effect: "read";
         readonly purpose: "List configured local Providers.";
+    }, {
+        readonly id: "share";
+        readonly usage: "frely share <port> [--ttl <hours>] [--rewrite-host] [--yes] [--json]";
+        readonly auth: "account";
+        readonly effect: "remote-write";
+        readonly purpose: "Make a web service on this computer (http://127.0.0.1:<port>) reachable from the Internet by a private link through Frely's relay, until Ctrl+C or expiry (at most 24 hours). Asks first. The relay allowance is a plan limit per UTC week; --rewrite-host sends Host: localhost to dev servers that refuse other names. Not the same as `frely provider share` (local models) or `frely tunnel` (command sandbox).";
+    }, {
+        readonly id: "service.share";
+        readonly usage: "frely service share --type mcp|a2a --port <n> [--label <text>] [--background] [--json]";
+        readonly auth: "account";
+        readonly effect: "remote-write";
+        readonly purpose: "Connect an MCP server or A2A Agent that runs on this computer (127.0.0.1:<port>) to Frely so you can sell it, without a public address: only Frely's own cloud can reach it, the port never leaves this computer, and Frely never supplies a target. Runs until Ctrl+C, or with --background the device background service keeps it connected. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance.";
+    }, {
+        readonly id: "service.manage";
+        readonly usage: "frely service list [--json] | stop <id|label> | remove <id|label>";
+        readonly auth: "account";
+        readonly effect: "remote-write";
+        readonly purpose: "List registered services, stop one on this computer (it stays registered), or remove it from Frely (products that pointed at it become unreachable).";
     }, {
         readonly id: "tunnel";
         readonly usage: "frely tunnel <host>:<port> [--local-port N]";
@@ -497,12 +695,90 @@ export declare function agentHelp(): {
         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: "devices";
+        readonly usage: "frely devices [--add] [--json]";
+        readonly auth: "controller";
+        readonly effect: "read";
+        readonly purpose: "List your Frely devices with online state and workspaces (list_devices). --add prints a one-time install command for a new computer.";
+    }, {
+        readonly id: "run";
+        readonly usage: "frely run <device> [--cwd <dir>] [--timeout <s>] [--background] -- <command> [--json] [--out <file>]";
+        readonly auth: "controller";
+        readonly effect: "remote-execution";
+        readonly purpose: "Run a shell command on a device inside its sandbox and print its output; --background returns a process id. The command's own failure is exit code 2.";
+    }, {
+        readonly id: "ps";
+        readonly usage: "frely ps <device>";
+        readonly auth: "controller";
+        readonly effect: "read";
+        readonly purpose: "List background commands on a device.";
+    }, {
+        readonly id: "logs";
+        readonly usage: "frely logs <device> <id> [--follow]";
+        readonly auth: "controller";
+        readonly effect: "read";
+        readonly purpose: "Output of a background command; --follow shows it live until it ends.";
+    }, {
+        readonly id: "kill";
+        readonly usage: "frely kill <device> <id>";
+        readonly auth: "controller";
+        readonly effect: "remote-execution";
+        readonly purpose: "Stop a background command on a device.";
+    }, {
+        readonly id: "read";
+        readonly usage: "frely read <device>:<path> [--lines a:b] [--json] [--out <file>]";
+        readonly auth: "controller";
+        readonly effect: "read";
+        readonly purpose: "Print a file on a device (UTF-8, up to 1 MiB). A Windows drive path such as C:\\x is this computer, not a device.";
+    }, {
+        readonly id: "ls";
+        readonly usage: "frely ls [<device>[:<path>]] [--json]";
+        readonly auth: "controller";
+        readonly effect: "read";
+        readonly purpose: "List a folder on a device; with only a device, its workspace roots.";
+    }, {
+        readonly id: "grep";
+        readonly usage: "frely grep <device>:<path> <text> [--regex] [--case] [--max <n>]";
+        readonly auth: "controller";
+        readonly effect: "read";
+        readonly purpose: "Search file contents on a device.";
+    }, {
+        readonly id: "edit";
+        readonly usage: "frely edit <device>:<path> (--from <local file> | --patch <json file>) [--overwrite]";
+        readonly auth: "controller";
+        readonly effect: "remote-write";
+        readonly purpose: "Write a device file from a local file, or apply line-range edits from a JSON file.";
+    }, {
+        readonly id: "permission";
+        readonly usage: "frely permission request <device> --resource <name> --reason <text> --command <text> | confirm <code> [A|B|C] | wait <short code> [--then '<command>']";
+        readonly auth: "controller";
+        readonly effect: "authorization";
+        readonly purpose: "Ask the owner to open what the device sandbox blocks. Exit code 3 prints the approval link and the wait command: show the link to the user, then run `frely permission wait <short code> --then '<original command>'` in the background so the original command runs once they approve.";
+    }, {
+        readonly id: "tools";
+        readonly usage: "frely tools [--json]";
+        readonly auth: "controller";
+        readonly effect: "read";
+        readonly purpose: "Print FrelyMCP's own instructions and every tool it offers.";
+    }, {
+        readonly id: "call";
+        readonly usage: "frely call <tool> [--json '<object>' | --input <file>] [--out <file>]";
+        readonly auth: "controller";
+        readonly effect: "subcommand-dependent";
+        readonly purpose: "Call any FrelyMCP tool by name (browser, models, web_fetch, local_mcp_call, store, ...).";
+    }, {
+        readonly id: "controller";
+        readonly usage: "frely controller login|logout|status";
+        readonly auth: "browser";
+        readonly effect: "authorization-if-needed";
+        readonly purpose: "Authorize this computer to control your devices: shows a short code, you open the link, type the code and confirm with a passkey or authenticator code. The first controller command does this by itself in a terminal.";
     }, {
         readonly id: "api";
         readonly usage: "frely api list|describe|call [--wait] [--help]";
-        readonly auth: "cloud-oauth";
+        readonly auth: "controller";
         readonly effect: "subcommand-dependent";
-        readonly purpose: "Discover and call your Frely account's business operations (the same tools FrelyMCP offers through frely_list/frely_call). The first call requests browser authorization. `list` is grouped and compact (add --json for the full tool list); use describe before call; parameters and results are JSON; --input reads a file up to 512 KiB. When a call needs the owner's approval the error links to it; run the call with --wait (in the foreground, tool timeout of at least 10 minutes) to show the user the link first and then block until they approve on their phone or the web, so the call finishes by itself and you need not be told. Never background or kill it.";
+        readonly purpose: "Discover and call your Frely account's business operations (the same tools FrelyMCP offers through frely_list/frely_call). Runs on this computer's controller authorization; the first call requests browser approval (frely controller login). `list` is grouped and compact (add --json for the full tool list); use describe before call; parameters and results are JSON; --input reads a file up to 512 KiB. When a call needs the owner's approval the error links to it; run the call with --wait (in the foreground, tool timeout of at least 10 minutes) to show the user the link first and then block until they approve on their phone or the web, so the call finishes by itself and you need not be told. Never background or kill it.";
     }, {
         readonly id: "app.install";
         readonly usage: "frely app install [--force] [--json]";

package/dist/agent-help.js

@@ -1,6 +1,6 @@
 import { VERSION } from "./version.js";
 export const COMMANDS = [
-    { id: "login", usage: "frely login [--relay <url>] [--no-browser] | frely login --email <address> [--invite <link>] [--mcp] [--workspace <path>] [--days <n>] then frely login --code <6-digit code>", auth: "browser-or-email", effect: "authorization", purpose: "Authorize the CLI for the user's Frely account. With --email, Frely emails a code; the user pastes it into `frely login --code` (enter only the 6 digits; the mail also shows a short reference such as K7, which is only for matching the mail). Add --mcp to also enable device MCP for the workspace (default 90 days) once the code is verified; do this when the user is registering for the first time, and tell them before asking for the code." },
+    { id: "login", usage: "frely login [--relay <url>] [--no-browser] | frely login --wait | frely login --email <address> [--invite <link>] [--mcp] [--workspace <path>] [--days <n>] then frely login --code <6-digit code>", auth: "browser-or-email", effect: "authorization", purpose: "Authorize the CLI for the user's Frely account. The browser form blocks until the user approves, then returns, so continue the task when it exits; if the command is stopped first, run `frely login --wait` to resume on the same link. With --email, Frely emails a code; the user pastes it into `frely login --code` (enter only the 6 digits; the mail also shows a short reference such as K7, which is only for matching the mail). Add --mcp to also enable device MCP for the workspace (default 90 days) once the code is verified; do this when the user is registering for the first time, and tell them before asking for the code." },
     { id: "logout", usage: "frely logout", auth: "none", effect: "local-write", purpose: "Remove login, revoke Cloud authorization and stop the MCP background service." },
     { id: "uninstall", usage: "frely uninstall [--yes] [--json]", auth: "optional-account", effect: "remote-write", purpose: "Remove Frely from this computer: revoke this device's Device MCP authorization, Cloud and account login on the Frely side, stop and uninstall the background service, delete saved login, device and MCP data, installed Agent Skills and the frely program itself. It lists everything first and removes nothing until the user types yes; without a terminal it only lists, and --yes confirms. Frely App and server-side Providers/Agents are not removed. Refuses to run inside device MCP. Destructive: run only when the user asks for it." },
     { id: "doctor", usage: "frely doctor [-v] [--json]", auth: "optional-account", effect: "diagnostic", purpose: "Show the signed-in account, installation, available updates, MCP and connection status; -v verifies the account online and runs detailed diagnostics." },
@@ -24,18 +24,41 @@ export const COMMANDS = [
     { id: "item.run", usage: "frely item run <script> [args...]", auth: "cloud-oauth", effect: "local-execution", purpose: "Run an encrypted paid script of an installed item inside the Frely command sandbox. The placeholder file at the script's path calls this for you. The access lease is renewed when it is near its end; without a valid pass the script does not run." },
     { id: "item.update", usage: "frely item update [<folder>] [--json]", auth: "cloud-oauth", effect: "local-write", purpose: "Without a folder, list the installed marketplace items and say which have a newer version; nothing is changed. With a folder, install the newer version into that folder, after you decide to. Frely never updates an item by itself. A folder you edited is refused, and a new version needs a new review (frely item trust) unless Frely's scan passed for it." },
     { id: "item.install", usage: "frely item install <username/name[@version]> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--dir <path>] [--json]", auth: "cloud-oauth", effect: "local-write", purpose: "Install a download-install Prompt or Skill from the marketplace through Frely Cloud. The paid part is installed only with a valid pass; otherwise the command prints how to buy one. Skills go to the host Skill folder, Prompts to --dir (default: current directory). Scripts are saved without execute permission." },
-    { id: "remote.tools", usage: "frely remote tools <username/name> [--json]", auth: "cloud-oauth", effect: "remote-read", purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP." },
-    { id: "remote.call", usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>]", auth: "cloud-oauth", effect: "remote-call", purpose: "Call one tool of a remote MCP product and print the result as JSON (exit code 1 when the tool reports an error). Each call is billed or needs a pass exactly as in an MCP client; ask the user before a call that writes data they did not ask for." },
-    { id: "remote.config", usage: "frely remote config <username/name> [--write <file>]", auth: "cloud-oauth", effect: "remote-write", purpose: "Get a new key for one remote MCP product (it replaces the previous one) and print the mcpServers JSON that MCP clients take for it; with --write the entry is merged into that JSON file (created 0600) instead of printed. The key works only for this MCP." },
+    { id: "remote.tools", usage: "frely remote tools <username/name> [--json] [--replace]", auth: "cloud-oauth", effect: "remote-read", purpose: "List the tools of a remote MCP product from the marketplace, with their input schemas, without configuring it in an MCP client. The first use asks Frely for a key that works only for this MCP. If the name now belongs to a different MCP than the one connected before, it stops; --replace switches to the new one." },
+    { id: "remote.call", usage: "frely remote call <username/name> <tool> [--json '<object>' | --input <file>] [--replace]", auth: "cloud-oauth", effect: "remote-call", purpose: "Call one tool of a remote MCP product and print the result as JSON (exit code 1 when the tool reports an error). Each call is billed or needs a pass exactly as in an MCP client; ask the user before a call that writes data they did not ask for." },
+    { id: "remote.config", usage: "frely remote config <username/name> [--write <file>] [--replace]", auth: "cloud-oauth", effect: "remote-write", purpose: "Get a new key for one remote MCP product (it replaces the previous one) and print the mcpServers JSON that MCP clients take for it; with --write the entry is merged into that JSON file (created 0600) instead of printed. The key works only for this MCP." },
     { id: "agent.install", usage: "frely agent install <username/name[@version]> [--host chatgpt|codex|claude-code|pi|generic] [--scope global|project] [--dir <project>] [--api-key-stdin] [--json]", auth: "optional-api-key", effect: "local-write", purpose: "Install the public Agent's trigger Skill; an API key goes only through stdin to secure storage." },
     { id: "agent.run", usage: "frely agent run <username/name> (--input <text>|--input-stdin) [--json]", auth: "installed-api-key-or-account", effect: "remote-call", purpose: "Send the complete relevant user request to the installed Agent through model-scoped MCP. Usage may be billed." },
     { id: "agent.status", usage: "frely agent status (<username/name>|--api-key-stdin [--relay <url>]) [--json]", auth: "none-or-api-key", effect: "read", purpose: "Inspect an installed Agent Skill and, for API-key installs, its Key budget. With --api-key-stdin, read that Key's budget without installing or logging in." },
     { id: "agent.remove", usage: "frely agent remove <username/name> [--json]", auth: "none", effect: "local-write", purpose: "Remove an installed Agent Skill and its saved API key." },
-    { id: "provider.share", usage: "frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]", auth: "account", effect: "remote-write", purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead." },
+    { id: "agent.local.add", usage: "frely agent local add <username/name | https://github.com/owner/repo> [--name <folder-name>]", auth: "optional-account", effect: "local-write", purpose: "Download an Agent's repository into its own folder under ~/frely-agents and run its setup inside the sandbox. The sandbox can write only that folder, cannot read credential folders and can reach only Frely's API plus the sites the repository lists in frely.yaml, each of which the owner approves once through a link (exit code 3 with the link when nobody can wait; approve, then run the same command again). Needs a frely.yaml with a local.run command." },
+    { id: "agent.local.start", usage: "frely agent local start <name> [--foreground]", auth: "account-and-api-key", effect: "local-process", purpose: "Run a local Agent in the background inside the sandbox. Its model calls go through a local proxy that adds the Frely API key (saved with `frely agent local key`), so the repository's code never sees it. Billed to the key like any other API call." },
+    { id: "agent.local.stop", usage: "frely agent local stop <name>", auth: "none", effect: "local-process", purpose: "Stop a running local Agent. Run start again afterwards to apply newly approved sites." },
+    { id: "agent.local.logs", usage: "frely agent local logs <name> [--lines <n>] [--follow]", auth: "none", effect: "read", purpose: "Show what a local Agent printed, including what the sandbox blocked." },
+    { id: "agent.local.list", usage: "frely agent local list [--json]", auth: "none", effect: "read", purpose: "List the Agents on this computer, whether each is running, and the sites each has been approved for." },
+    { id: "agent.local.remove", usage: "frely agent local remove <name>", auth: "none", effect: "local-write", purpose: "Stop a local Agent and delete its folder and records. Only the Agent's own folder is removed." },
+    { id: "agent.local.key", usage: "frely agent local key --api-key-stdin | --clear", auth: "account", effect: "local-write", purpose: "Save the Frely API key that local Agents use for model calls; it goes only through stdin to secure storage. FRELY_API_KEY overrides it." },
+    { id: "provider.share", usage: "frely provider share [ollama|openai-compatible] [--url <loopback-v1-url>] [--models <a,b>] [--slot <slot-id>] [--name <name>]", auth: "account", effect: "remote-write", purpose: "Publish a local model Provider. If a prepared Provider on this device is not finished, resume it instead. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance." },
     { id: "provider.list", usage: "frely provider list [--json]", auth: "account", effect: "read", purpose: "List configured local Providers." },
+    { id: "share", usage: "frely share <port> [--ttl <hours>] [--rewrite-host] [--yes] [--json]", auth: "account", effect: "remote-write", purpose: "Make a web service on this computer (http://127.0.0.1:<port>) reachable from the Internet by a private link through Frely's relay, until Ctrl+C or expiry (at most 24 hours). Asks first. The relay allowance is a plan limit per UTC week; --rewrite-host sends Host: localhost to dev servers that refuse other names. Not the same as `frely provider share` (local models) or `frely tunnel` (command sandbox)." },
+    { id: "service.share", usage: "frely service share --type mcp|a2a --port <n> [--label <text>] [--background] [--json]", auth: "account", effect: "remote-write", purpose: "Connect an MCP server or A2A Agent that runs on this computer (127.0.0.1:<port>) to Frely so you can sell it, without a public address: only Frely's own cloud can reach it, the port never leaves this computer, and Frely never supplies a target. Runs until Ctrl+C, or with --background the device background service keeps it connected. Prints this week's remaining relay allowance; relayed traffic counts against the weekly relay allowance." },
+    { id: "service.manage", usage: "frely service list [--json] | stop <id|label> | remove <id|label>", auth: "account", effect: "remote-write", purpose: "List registered services, stop one on this computer (it stays registered), or remove it from Frely (products that pointed at it become unreachable)." },
     { id: "tunnel", usage: "frely tunnel <host>:<port> [--local-port N]", auth: "none", effect: "local-execution", 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." },
     { id: "sandbox.proxy", usage: "frely sandbox proxy [<http://host:port> [--no-proxy <list>] | --clear]", auth: "none", effect: "local-write", 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." },
-    { id: "api", usage: "frely api list|describe|call [--wait] [--help]", auth: "cloud-oauth", effect: "subcommand-dependent", purpose: "Discover and call your Frely account's business operations (the same tools FrelyMCP offers through frely_list/frely_call). The first call requests browser authorization. `list` is grouped and compact (add --json for the full tool list); use describe before call; parameters and results are JSON; --input reads a file up to 512 KiB. When a call needs the owner's approval the error links to it; run the call with --wait (in the foreground, tool timeout of at least 10 minutes) to show the user the link first and then block until they approve on their phone or the web, so the call finishes by itself and you need not be told. Never background or kill it." },
+    { id: "devices", usage: "frely devices [--add] [--json]", auth: "controller", effect: "read", purpose: "List your Frely devices with online state and workspaces (list_devices). --add prints a one-time install command for a new computer." },
+    { id: "run", usage: "frely run <device> [--cwd <dir>] [--timeout <s>] [--background] -- <command> [--json] [--out <file>]", auth: "controller", effect: "remote-execution", purpose: "Run a shell command on a device inside its sandbox and print its output; --background returns a process id. The command's own failure is exit code 2." },
+    { id: "ps", usage: "frely ps <device>", auth: "controller", effect: "read", purpose: "List background commands on a device." },
+    { id: "logs", usage: "frely logs <device> <id> [--follow]", auth: "controller", effect: "read", purpose: "Output of a background command; --follow shows it live until it ends." },
+    { id: "kill", usage: "frely kill <device> <id>", auth: "controller", effect: "remote-execution", purpose: "Stop a background command on a device." },
+    { id: "read", usage: "frely read <device>:<path> [--lines a:b] [--json] [--out <file>]", auth: "controller", effect: "read", purpose: "Print a file on a device (UTF-8, up to 1 MiB). A Windows drive path such as C:\\x is this computer, not a device." },
+    { id: "ls", usage: "frely ls [<device>[:<path>]] [--json]", auth: "controller", effect: "read", purpose: "List a folder on a device; with only a device, its workspace roots." },
+    { id: "grep", usage: "frely grep <device>:<path> <text> [--regex] [--case] [--max <n>]", auth: "controller", effect: "read", purpose: "Search file contents on a device." },
+    { id: "edit", usage: "frely edit <device>:<path> (--from <local file> | --patch <json file>) [--overwrite]", auth: "controller", effect: "remote-write", purpose: "Write a device file from a local file, or apply line-range edits from a JSON file." },
+    { id: "permission", usage: "frely permission request <device> --resource <name> --reason <text> --command <text> | confirm <code> [A|B|C] | wait <short code> [--then '<command>']", auth: "controller", effect: "authorization", purpose: "Ask the owner to open what the device sandbox blocks. Exit code 3 prints the approval link and the wait command: show the link to the user, then run `frely permission wait <short code> --then '<original command>'` in the background so the original command runs once they approve." },
+    { id: "tools", usage: "frely tools [--json]", auth: "controller", effect: "read", purpose: "Print FrelyMCP's own instructions and every tool it offers." },
+    { id: "call", usage: "frely call <tool> [--json '<object>' | --input <file>] [--out <file>]", auth: "controller", effect: "subcommand-dependent", purpose: "Call any FrelyMCP tool by name (browser, models, web_fetch, local_mcp_call, store, ...)." },
+    { id: "controller", usage: "frely controller login|logout|status", auth: "browser", effect: "authorization-if-needed", purpose: "Authorize this computer to control your devices: shows a short code, you open the link, type the code and confirm with a passkey or authenticator code. The first controller command does this by itself in a terminal." },
+    { id: "api", usage: "frely api list|describe|call [--wait] [--help]", auth: "controller", effect: "subcommand-dependent", purpose: "Discover and call your Frely account's business operations (the same tools FrelyMCP offers through frely_list/frely_call). Runs on this computer's controller authorization; the first call requests browser approval (frely controller login). `list` is grouped and compact (add --json for the full tool list); use describe before call; parameters and results are JSON; --input reads a file up to 512 KiB. When a call needs the owner's approval the error links to it; run the call with --wait (in the foreground, tool timeout of at least 10 minutes) to show the user the link first and then block until they approve on their phone or the web, so the call finishes by itself and you need not be told. Never background or kill it." },
     { id: "app.install", usage: "frely app install [--force] [--json]", auth: "local", effect: "local-write", purpose: "Install the Frely App: Homebrew cask when available, otherwise a verified download (SHA-256) from the FrelyHQ/frely-cli release mirror; quarantine is preserved." },
     { id: "app.open", usage: "frely app open [--window]", auth: "local", effect: "local-write", purpose: "Launch the Frely App in the background (menu bar) or with its main window via --window." },
     { id: "app.status", usage: "frely app status [--json]", auth: "local", effect: "read", purpose: "Show whether the Frely App is installed, its version, install path, running state and how it is managed." },
@@ -72,12 +95,14 @@ export function agentHelp() {
     };
 }
 const GROUPS = [
+    { title: "Control your devices", ids: ["devices", "run", "ps", "logs", "kill", "read", "ls", "grep", "edit", "permission", "tools", "call", "controller"] },
     { title: "Account", ids: ["login", "logout", "uninstall", "doctor", "update"] },
     { title: "Device MCP", ids: ["mcp.start", "mcp.workspace", "mcp.local", "mcp.lifecycle"] },
-    { title: "Agents", ids: ["agent.install", "agent.run", "agent.status", "agent.remove"] },
+    { title: "Agents", ids: ["agent.install", "agent.run", "agent.status", "agent.remove", "agent.local"] },
     { title: "Skills", ids: ["skill.install"] },
     { title: "Marketplace items", ids: ["item.install", "item.update", "item.run", "item.trust"] },
     { title: "Providers", ids: ["provider.share", "provider.list"] },
+    { title: "Share", ids: ["share", "service.share", "service.manage"] },
     { title: "Command sandbox", ids: ["tunnel", "sandbox.proxy"] },
     { title: "API", ids: ["api", "remote.tools", "remote.call", "remote.config"] },
 ];
@@ -86,6 +111,19 @@ const GROUPS = [
 // --json`, which this overview points to for the complete contract. Commands
 // meant for services and Agents (mcp serve/stdio, network) appear only there.
 const SHORT_USAGE = {
+    devices: "frely devices [--add]",
+    run: "frely run <device> [--cwd <dir>] [--background] -- <command>",
+    ps: "frely ps <device>",
+    logs: "frely logs <device> <id> [--follow]",
+    kill: "frely kill <device> <id>",
+    read: "frely read <device>:<path> [--lines a:b]",
+    ls: "frely ls [<device>[:<path>]]",
+    grep: "frely grep <device>:<path> <text>",
+    edit: "frely edit <device>:<path> --from <file>",
+    permission: "frely permission request|confirm|wait",
+    tools: "frely tools",
+    call: "frely call <tool> [--json '<object>']",
+    controller: "frely controller login|logout|status",
     login: "frely login [--no-browser]",
     logout: "frely logout",
     uninstall: "frely uninstall [--yes]",
@@ -104,8 +142,19 @@ const SHORT_USAGE = {
     "agent.run": "frely agent run <username/name> (--input <text>|--input-stdin)",
     "agent.status": "frely agent status <username/name>",
     "agent.remove": "frely agent remove <username/name>",
+    "agent.local": "frely agent local add|start|stop|logs|list|remove|key",
+    "agent.local.add": "frely agent local add <username/name | github-url>",
+    "agent.local.start": "frely agent local start <name>",
+    "agent.local.stop": "frely agent local stop <name>",
+    "agent.local.logs": "frely agent local logs <name> [--follow]",
+    "agent.local.list": "frely agent local list",
+    "agent.local.remove": "frely agent local remove <name>",
+    "agent.local.key": "frely agent local key --api-key-stdin",
     "provider.share": "frely provider share [ollama|openai-compatible] [--models <a,b>]",
     "provider.list": "frely provider list",
+    share: "frely share <port> [--ttl <hours>]",
+    "service.share": "frely service share --type mcp|a2a --port <n>",
+    "service.manage": "frely service list|stop|remove",
     tunnel: "frely tunnel <host>:<port> [--local-port N]",
     "sandbox.proxy": "frely sandbox proxy [<url> [--no-proxy <list>] | --clear]",
     api: "frely api list|describe|call",