@tinycloud/cli 1.5.0-beta.27 → 1.5.0-beta.29

package/README.md

@@ -1,51 +1,49 @@
 # @tinycloud/cli
 
-Self-sovereign storage from the terminal. `tc` is the command-line interface for [TinyCloud](https://tinycloud.xyz) — manage data, delegations, spaces, and nodes without leaving your shell.
+Self-sovereign storage from the terminal. `tinycloud` is the command-line interface for [TinyCloud](https://tinycloud.xyz) — manage data, delegations, spaces, and nodes without leaving your shell.
 
 ## Install
 
 ```bash
-npm install -g @tinycloud/cli
+npm install -g @tinycloud/cli@1.5.0-beta.20
 ```
 
 Requires Node.js >= 20.
 
-The package installs two identical commands: `tc` and `tinycloud`. On Linux,
-iproute2 installs `/usr/sbin/tc` (traffic control), which can shadow `tc` on
-PATH; `tinycloud` avoids that clash and accepts the same arguments. If the npm global prefix is root-owned, run
-`npm config set prefix ~/.local` before installing: Ubuntu's default PATH puts
-`~/.local/bin` before `/usr/sbin`, but `~/.profile` adds it only if the
-directory existed at login, so start a new login shell after the first
-install. Run `hash -r` if `tc` already ran in the same shell. Verify with
-`command -v tc`, or call `"$(npm prefix --global)/bin/tc"` when in doubt.
+The package exposes `tinycloud` as its preferred command and keeps `tc` as a
+deprecated compatibility alias at the same entry. Both names accept the same
+commands and flags, with identical exit codes and stdout. A POSIX `tc` executable
+link emits one deprecation notice on stderr, never stdout. On Linux,
+`/usr/sbin/tc` is iproute2's traffic-control tool. Verify the pinned install
+with `tinycloud --version`.
 
 ## Agent skills
 
-The package ships the general `tc-cli` skill and its references in
-`skills/tc-cli`, and the `courier` skill for `tc courier` in `skills/courier`.
-See [skill installation](skills/tc-cli/INSTALL.md) for a
+The package ships the general `tinycloud-cli` skill and its references in
+`skills/tinycloud-cli`, and the `courier` skill for `tinycloud courier` in `skills/courier`.
+See [skill installation](skills/tinycloud-cli/INSTALL.md) for a
 pinned, cross-agent installation with OpenCode, Codex and Claude Code, and
-[authentication](skills/tc-cli/AUTH.md) for device login and relaying the
+[authentication](skills/tinycloud-cli/AUTH.md) for device login and relaying the
 approval code to the owner.
 
 ## Courier
 
-`tc courier …` runs [Courier](https://github.com/TinyCloudLabs/js-sdk/tree/master/packages/courier#readme), agent-to-agent threads
+`tinycloud courier …` runs [Courier](https://github.com/TinyCloudLabs/js-sdk/tree/master/packages/courier#readme), agent-to-agent threads
 over TinyCloud, bundled from `@tinycloud/courier` (beta). It takes the same
 arguments as the standalone `courier` bin and keeps its own agent identity in
-`$COURIER_HOME` (default `~/.courier`), not in a tc profile, so put every flag
+`$COURIER_HOME` (default `~/.courier`), not in a tinycloud profile, so put every flag
 after `courier`:
 
 ```bash
-tc courier init --paste --handle alice   # the owner approves in OpenKey; paste the XXXX-XXXX code
-tc courier inbox
-tc courier --help
+tinycloud courier init --paste --handle alice   # the owner approves in OpenKey; paste the XXXX-XXXX code
+tinycloud courier inbox
+tinycloud courier --help
 ```
 
 ## Operations coverage
 
-The migrated `tc secrets get` path is owned by `@tinycloud/operations` and
-uses delegated authority by default. `tc auth import` is partially migrated:
+The migrated `tinycloud secrets get` path is owned by `@tinycloud/operations` and
+uses delegated authority by default. `tinycloud auth import` is partially migrated:
 the request-bound active-session v1 path is canonical, while legacy delegation
 and permission input forms remain Commander-owned. The complete registration
 ledger is checked in `../operations/coverage.json` and checked against the
@@ -61,51 +59,50 @@ fallback for delegated execution.
 
 ```bash
 # Set up a profile and generate keys
-tc init
+tinycloud init
 
 # Authenticate via browser
-tc auth login
+tinycloud auth login
 
 # Authenticate on a remote/headless machine: the owner approves an explicit
 # manifest on their phone (URL + code printed to stderr). Use a new profile
 # name if it already exists; keep the user's existing profiles.
-tc init --name publisher --key-only
-tc --profile publisher auth login --device --manifest builtin:share-publishing
+tinycloud init --name publisher --key-only
+tinycloud --profile publisher auth login --device --manifest builtin:share-publishing
 
 # Same Share publishing scope, as a shortcut (on the dedicated profile)
-tc --profile publisher enable share
+tinycloud --profile publisher enable share
 
 # Selected profile, owner, host and space (JSON; does not test access)
-tc context
+tinycloud context
 
 # Store and retrieve data
-tc kv put greeting "Hello, world"
-tc kv get greeting
-tc kv list
+tinycloud kv put greeting "Hello, world"
+tinycloud kv get greeting
+tinycloud kv list
 
 # Manage network-encrypted secrets on the default network
-tc secrets network init
-printf '%s' "$ANTHROPIC_API_KEY" | tc secrets put ANTHROPIC_API_KEY --stdin
-tc secrets get ANTHROPIC_API_KEY
-tc secrets run ANTHROPIC_API_KEY -- python train.py   # the value only in the command's environment
+tinycloud secrets network init
+printf '%s' "$ANTHROPIC_API_KEY" | tinycloud secrets put ANTHROPIC_API_KEY --stdin
+tinycloud secrets get ANTHROPIC_API_KEY
+tinycloud secrets run ANTHROPIC_API_KEY -- python train.py   # the value only in the command's environment
 
 # Ask the owner for a secret an agent needs, then wait for it
-# (call TinyCloud's CLI by absolute path: a bare `tc` can be iproute2's /usr/sbin/tc)
-TC_BIN="$(npm prefix --global)/bin/tc"
-"$TC_BIN" --profile agent secrets request OPENAI_API_KEY --json   # offline; prints the owner's link
-"$TC_BIN" --profile agent secrets wait OPENAI_API_KEY --timeout 9m --json   # 0 ready, 8 pending
+# (call TinyCloud's CLI by absolute path when using tc: a bare tc can be iproute2's /usr/sbin/tc)
+tinycloud --profile agent secrets request OPENAI_API_KEY --json   # offline; prints the owner's link
+tinycloud --profile agent secrets wait OPENAI_API_KEY --timeout 9m --json   # 0 ready, 8 pending
 
 # Manage spaces
-tc space list
-tc space create
+tinycloud space list
+tinycloud space create
 
 # Grant access to another user
-tc delegation create --to did:pkh:eip155:1:0x...
+tinycloud delegation create --to did:pkh:eip155:1:0x...
 ```
 
 ## Home feed
 
-`tc feed` uses separate owner-provisioned SQLite databases for each agent's
+`tinycloud feed` uses separate owner-provisioned SQLite databases for each agent's
 cards/handling and the owner's append-only responses. Owner registry and view
 state live separately. SDK consumers use the same contract from
 `@tinycloud/sdk-services/feed` with existing SQL database handles; see the
@@ -121,10 +118,10 @@ Create a separate agent profile and set `AGENT_DID` to its printed DID. Use the
 same node as the owner:
 
 ```bash
-tc profile create feed-agent --posture delegate-session --operator agent
-tc --profile owner feed connect --agent writer --to "$AGENT_DID" --label Writer \
+tinycloud profile create feed-agent --posture delegate-session --operator agent
+tinycloud --profile owner feed connect --agent writer --to "$AGENT_DID" --label Writer \
   --space applications > feed-grant.json
-tc --profile feed-agent auth import feed-grant.json
+tinycloud --profile feed-agent auth import feed-grant.json
 ```
 
 `connect` reserves a stable token/DID/resource binding, provisions both schemas,
@@ -144,8 +141,8 @@ Publish `card.json` from the agent profile:
 ```
 
 ```bash
-tc --profile feed-agent feed publish --agent writer --file card.json
-tc --profile feed-agent feed watch --agent writer --recipient agent-runtime \
+tinycloud --profile feed-agent feed publish --agent writer --file card.json
+tinycloud --profile feed-agent feed watch --agent writer --recipient agent-runtime \
   --runner '["node","agent-handler.js"]'
 ```
 
@@ -157,10 +154,10 @@ profile in another terminal, or answer the card through Home:
 ```
 
 ```bash
-tc --profile owner feed respond --agent writer --file response.json
-tc --profile feed-agent feed responses --agent writer --after 0
-tc --profile feed-agent feed handling --agent writer --file handling.json
-tc --profile owner feed show card-draft-01 --agent writer
+tinycloud --profile owner feed respond --agent writer --file response.json
+tinycloud --profile feed-agent feed responses --agent writer --after 0
+tinycloud --profile feed-agent feed handling --agent writer --file handling.json
+tinycloud --profile owner feed show card-draft-01 --agent writer
 ```
 
 For an explicit outbound note to that agent, save a separate `message.json`:
@@ -170,7 +167,7 @@ For an explicit outbound note to that agent, save a separate `message.json`:
 ```
 
 ```bash
-tc --profile owner feed message --agent writer --file message.json
+tinycloud --profile owner feed message --agent writer --file message.json
 ```
 
 Messages also work on information cards with `needsResponse: false`. They do not
@@ -190,8 +187,8 @@ JSON envelope, for example:
 Include it on the **first** save, instead of the plain `respond` command above:
 
 ```bash
-tc --profile owner feed respond --agent writer --file response.json --payload-file payload.json
-tc --profile feed-agent feed payload --agent writer --response response-draft-01 \
+tinycloud --profile owner feed respond --agent writer --file response.json --payload-file payload.json
+tinycloud --profile feed-agent feed payload --agent writer --response response-draft-01 \
   --card card-draft-01 --revision 1 --issuance issuance-draft-01
 ```
 
@@ -251,56 +248,56 @@ execution is not promised.
 
 | Command | Description |
 |---------|-------------|
-| `tc init` | Set up a profile and generate keys |
-| `tc auth login` | Authenticate via browser |
-| `tc auth login --device --manifest <file>` | Approve exactly a manifest's permissions on another device (phone) |
-| `tc auth login --manifest <file>` | Browser OpenKey login scoped to a manifest |
-| `tc enable share` | Device login with the built-in Share publishing manifest (use a dedicated profile) |
-| `tc context` | Show the selected profile, owner, host, space and session state |
-| `tc auth status` | Show authentication status |
-| `tc auth whoami` | Show current identity |
-| `tc auth request --preset apps-agent [--app <id>]... [--write]` | Request access for an agent to the user's installed apps: read-only by default, for one app, several, or all. `--write --app <id>` also lets the agent change that app's data: write its `knowledge/` and `prefs/` files and add, change or delete its table rows. For the Health Log app's catalog database, it can also create, change and drop tables (nodes before 1.21.6 do not enforce that split). It cannot change the app's code, manifest or install record |
-| `tc knowledge list` | List the installed apps that have a knowledge bundle |
-| `tc knowledge read <app_id> [concept]` | Read an app's knowledge index, or one concept with its frontmatter parsed |
-| `tc apps install <app_id>` | Install a pinned catalog app into the applications space of the profile it runs under (the owner's, for a delegate profile, through its grant): each file is verified against its pinned digest, the pinned DDL runs only if every statement is allowed, and knowledge notes are created create-only. Notes you have edited are left as they are and reported (exit 0) |
-| `tc kv get <key>` | Retrieve a value |
-| `tc kv put <key> <value>` | Store a value |
-| `tc kv list` | List all keys |
-| `tc sql query <sql>` | Run a SQLite SELECT query |
-| `tc sql execute <sql>` | Run a SQLite write or schema statement |
-| `tc sql export` | Export a SQLite database file |
-| `tc feed` | Connect an agent, publish cards, save responses, record handling, and watch for runtime handoff; see [Home feed](#home-feed) |
-| `tc space list` | List your spaces |
-| `tc space create` | Create a new space |
-| `tc delegation create` | Grant access to another user |
-| `tc delegation list` | List delegations |
-| `tc delegation revoke <cid>` | Revoke a delegation. From a delegate profile, revoke one its own key issued. |
-| `tc share` | Share data with another user |
-| `tc node` | Manage TinyCloud nodes |
-| `tc profile list` | List profiles |
-| `tc profile show` | Show profile details |
-| `tc profile create` | Create a new profile |
-| `tc vault` | Manage encrypted KV vaults |
-| `tc secrets` | Manage network-encrypted secrets |
-| `tc secrets network show` | Show a secrets decryption network |
-| `tc secrets network init` | Create or fetch the default secrets network |
-| `tc secrets network grant` | Grant `tinycloud.encryption/decrypt` on a secrets network |
-| `tc secrets run` | Run a command with secrets in its environment |
-| `tc secrets request` | Print a Secret Manager link asking the owner to add secrets (offline) |
-| `tc secrets wait` | Wait until secrets exist and are readable (never signs in; needs a stored session; exit 8 pending, 130 interrupted) |
-| `tc secrets manage` | Print or open the Secret Manager page, `{url, opened}` |
-| `tc vars` | Manage environment variables |
-| `tc doctor` | Run diagnostic checks |
-| `tc completion` | Generate shell completions |
-| `tc courier` | Agent-to-agent threads over TinyCloud (beta; see [Courier](#courier)) |
+| `tinycloud init` | Set up a profile and generate keys |
+| `tinycloud auth login` | Authenticate via browser |
+| `tinycloud auth login --device --manifest <file>` | Approve exactly a manifest's permissions on another device (phone) |
+| `tinycloud auth login --manifest <file>` | Browser OpenKey login scoped to a manifest |
+| `tinycloud enable share` | Device login with the built-in Share publishing manifest (use a dedicated profile) |
+| `tinycloud context` | Show the selected profile, owner, host, space and session state |
+| `tinycloud auth status` | Show authentication status |
+| `tinycloud auth whoami` | Show current identity |
+| `tinycloud auth request --preset apps-agent [--app <id>]... [--write]` | Request access for an agent to the user's installed apps: read-only by default, for one app, several, or all. `--write --app <id>` also lets the agent change that app's data: write its `knowledge/` and `prefs/` files and add, change or delete its table rows. For the Health Log app's catalog database, it can also create, change and drop tables (nodes before 1.21.6 do not enforce that split). It cannot change the app's code, manifest or install record |
+| `tinycloud knowledge list` | List the installed apps that have a knowledge bundle |
+| `tinycloud knowledge read <app_id> [concept]` | Read an app's knowledge index, or one concept with its frontmatter parsed |
+| `tinycloud apps install <app_id>` | Install a pinned catalog app into the applications space of the profile it runs under (the owner's, for a delegate profile, through its grant): each file is verified against its pinned digest, the pinned DDL runs only if every statement is allowed, and knowledge notes are created create-only. Notes you have edited are left as they are and reported (exit 0) |
+| `tinycloud kv get <key>` | Retrieve a value |
+| `tinycloud kv put <key> <value>` | Store a value |
+| `tinycloud kv list` | List all keys |
+| `tinycloud sql query <sql>` | Run a SQLite SELECT query |
+| `tinycloud sql execute <sql>` | Run a SQLite write or schema statement |
+| `tinycloud sql export` | Export a SQLite database file |
+| `tinycloud feed` | Connect an agent, publish cards, save responses, record handling, and watch for runtime handoff; see [Home feed](#home-feed) |
+| `tinycloud space list` | List your spaces |
+| `tinycloud space create` | Create a new space |
+| `tinycloud delegation create` | Grant access to another user |
+| `tinycloud delegation list` | List delegations |
+| `tinycloud delegation revoke <cid>` | Revoke a delegation. From a delegate profile, revoke one its own key issued. |
+| `tinycloud share` | Share data with another user |
+| `tinycloud node` | Manage TinyCloud nodes |
+| `tinycloud profile list` | List profiles |
+| `tinycloud profile show` | Show profile details |
+| `tinycloud profile create` | Create a new profile |
+| `tinycloud vault` | Manage encrypted KV vaults |
+| `tinycloud secrets` | Manage network-encrypted secrets |
+| `tinycloud secrets network show` | Show a secrets decryption network |
+| `tinycloud secrets network init` | Create or fetch the default secrets network |
+| `tinycloud secrets network grant` | Grant `tinycloud.encryption/decrypt` on a secrets network |
+| `tinycloud secrets run` | Run a command with secrets in its environment |
+| `tinycloud secrets request` | Print a Secret Manager link asking the owner to add secrets (offline) |
+| `tinycloud secrets wait` | Wait until secrets exist and are readable (never signs in; needs a stored session; exit 8 pending, 130 interrupted) |
+| `tinycloud secrets manage` | Print or open the Secret Manager page, `{url, opened}` |
+| `tinycloud vars` | Manage environment variables |
+| `tinycloud doctor` | Run diagnostic checks |
+| `tinycloud completion` | Generate shell completions |
+| `tinycloud courier` | Agent-to-agent threads over TinyCloud (beta; see [Courier](#courier)) |
 
 Secret names are env-style uppercase identifiers such as `FIREFLIES_API_KEY`.
-`tc secrets network show` accepts either a short network name or a full
-`urn:tinycloud:encryption:<ownerDid>:<network>` identifier. `tc secrets
+`tinycloud secrets network show` accepts either a short network name or a full
+`urn:tinycloud:encryption:<ownerDid>:<network>` identifier. `tinycloud secrets
 network grant` takes the short name, resolves the network, and grants
 `tinycloud.encryption/decrypt`.
 
-`tc apps install` re-creates the pinned views on every run (reported as
+`tinycloud apps install` re-creates the pinned views on every run (reported as
 `viewsRecreated`). Knowledge notes whose bytes differ from the pinned version
 are left as you edited them and listed under `conflicts` (JSON); the command
 still exits 0 and installs the rest. If the schema fails after notes were
@@ -310,55 +307,55 @@ is safe.
 ### Running a command with secrets
 
 ```bash
-tc secrets run NAME... [--map NAME=ENV_VAR]... [--scope S] [--space S] [--delegation SOURCE] [--private-key HEX] -- <command> [args...]
+tinycloud secrets run NAME... [--map NAME=ENV_VAR]... [--scope S] [--space S] [--delegation SOURCE] [--private-key HEX] -- <command> [args...]
 
-tc secrets run ANTHROPIC_API_KEY OPENAI_API_KEY -- python train.py
-tc secrets run --map ANTHROPIC_KEY=ANTHROPIC_API_KEY -- node server.js
+tinycloud secrets run ANTHROPIC_API_KEY OPENAI_API_KEY -- python train.py
+tinycloud secrets run --map ANTHROPIC_KEY=ANTHROPIC_API_KEY -- node server.js
 ```
 
-`tc secrets run` reads every named secret as `tc secrets get` does, then
+`tinycloud secrets run` reads every named secret as `tinycloud secrets get` does, then
 starts `<command>` directly, without a shell, with each value in its
 environment: under the secret's name, or under `ENV_VAR` for `--map
 NAME=ENV_VAR`. A value replaces an inherited variable of the same name.
-tc doesn't pass its own `TC_PRIVATE_KEY` to the command. To give the command
+tinycloud doesn't pass its own `TC_PRIVATE_KEY` to the command. To give the command
 a key from a secret, use `--map NAME=TC_PRIVATE_KEY`.
 Everything after the first `--`, including any further `--`, goes to the
-command unchanged. The command uses tc's stdin, stdout and stderr; tc itself
+command unchanged. The command uses tinycloud's stdin, stdout and stderr; tinycloud itself
 writes nothing to stdout, and its own messages go to stderr.
 
 Name at least one secret, as an argument or with `--map`. `ENV_VAR` must
 match `[A-Za-z_][A-Za-z0-9_]*`, and two secrets cannot be mapped to the same
 variable (exit 2). If any secret cannot be read, the command does not start
-and tc exits with the code and error `tc secrets get` gives for that secret.
-Otherwise tc exits with the command's exit code. If the command was ended by
-SIGINT, SIGTERM, SIGHUP, SIGKILL, SIGALRM or SIGUSR2, tc ends by the same
+and tinycloud exits with the code and error `tinycloud secrets get` gives for that secret.
+Otherwise tinycloud exits with the command's exit code. If the command was ended by
+SIGINT, SIGTERM, SIGHUP, SIGKILL, SIGALRM or SIGUSR2, tinycloud ends by the same
 signal (or exits with 128 plus the signal number if that signal doesn't end
-tc). If any other signal ended it, such as SIGQUIT or SIGSEGV, tc exits with
-128 plus the signal number instead, so tc does not cause a core dump
+tinycloud). If any other signal ended it, such as SIGQUIT or SIGSEGV, tinycloud exits with
+128 plus the signal number instead, so tinycloud does not cause a core dump
 (SIGUSR1 and SIGPIPE are left out too: Node uses SIGUSR1 for its inspector
 and ignores SIGPIPE).
 
-SIGINT, SIGTERM, SIGHUP and SIGQUIT sent to tc go to the command. When tc
+SIGINT, SIGTERM, SIGHUP and SIGQUIT sent to tinycloud go to the command. When tinycloud
 runs in the foreground of a terminal, it doesn't pass on SIGINT, SIGQUIT or
 SIGHUP: the terminal already sends them (Ctrl-C, Ctrl-\, hangup) to the
-command, so the command normally gets each one once. tc checks whether it's
+command, so the command normally gets each one once. tinycloud checks whether it's
 in the foreground using `/proc`, or `ps` where `/proc` isn't available. If
-neither works, it passes the signals on. When tc runs in the background, it
+neither works, it passes the signals on. When tinycloud runs in the background, it
 passes them on, so a signal sent to the whole job (for example `kill -INT
 %1`) can reach the command twice.
 
-From a script, stop the command by sending SIGTERM to tc's process ID. tc
+From a script, stop the command by sending SIGTERM to tinycloud's process ID. tinycloud
 passes it on, waits for the command to exit, then exits the way the command
 did (the command's own exit code if it handles SIGTERM itself). If the
-command ignores SIGTERM, tc keeps waiting.
+command ignores SIGTERM, tinycloud keeps waiting.
 
 A command that does not exist exits 127; one that cannot be executed, or
 cannot be started for another reason, exits 126. These cases print one plain
-line on stderr, even with `--json`: `tc secrets run: <command>: command not
+line on stderr, even with `--json`: `tinycloud secrets run: <command>: command not
 found`, `…: permission denied` or `…: cannot run (<error code>)`.
 
-Limits: `tc secrets run` keeps values out of the command line, your shell
-history and tc's own output. It doesn't hide them from the command: the
+Limits: `tinycloud secrets run` keeps values out of the command line, your shell
+history and tinycloud's own output. It doesn't hide them from the command: the
 command, and anything it starts, receives the values and can print, log or
 pass them on. Other programs running as the same user can often read a
 process's environment too.
@@ -380,7 +377,7 @@ process's environment too.
 Replication is off by default. `--replication` enables it for one invocation;
 `--no-replication` overrides `TC_REPLICATION=1`, and `--replication-debug`
 writes diagnostics to stderr. Save explicit login prefixes with
-`tc auth login --replication-prefix notes/`; saved prefixes are reapplied on
+`tinycloud auth login --replication-prefix notes/`; saved prefixes are reapplied on
 later logins and rotation. Prefixes are folders (`notes/`) or `/` for the
 whole space. Whole-space replication requires `kv-sync-root` support and
 `--replication-allow-secrets`, because it includes `vault/`. Replication needs
@@ -401,7 +398,7 @@ Chromium browsers that enforce Local Network Access without granting it (headles
 Chromium cannot show the prompt), may block the HTTPS page's plain-HTTP loopback
 callback: use an interactive CLI terminal and paste the same one-line code shown
 by OpenKey, or start with
-`tc auth login --method openkey --replication-prefix notes/ --owner DID --paste`
+`tinycloud auth login --method openkey --replication-prefix notes/ --owner DID --paste`
 for a headless terminal. Non-TTY `--no-popup` cannot accept a paste; if that
 callback fails, it exits nonzero at the five-minute expiry with a `--paste`
 retry hint and discards the candidate key. Restarting requires a new approval
@@ -409,10 +406,20 @@ and cannot reuse the old signed code. Ctrl-C, SIGINT or SIGTERM before approval
 arrives cancels the OpenKey handoff (best effort) and exits 130 `CANCELLED`
 without saving a key or session.
 
-Use `tc replica report` for read-only aggregates of persisted replication events
+Normal OpenKey login prints a short approval link on stderr and waits. Relay it
+to the owner from a headless or remote CLI; no localhost callback or pasted code
+is needed. `--no-popup` skips opening a local browser, not automatic result
+retrieval. The CLI verifies the encrypted result, durably saves it, then
+acknowledges delivery. Re-run the same command after an interruption to resume.
+The one-hour request expiry is independent of the requested grant lifetime and
+result retention. Normal login keeps its seven-day default; onboarding requests
+30 days explicitly. `--paste` remains an explicit manual fallback with a
+five-minute, single-use return code, not the automatic short-link transport.
+
+Use `tinycloud replica report` for read-only aggregates of persisted replication events
 and identity partitions. Live replica status is unavailable there. Report
 `--purge` and `--clear-pending` refuse with exit 2 `REPORT_READ_ONLY`.
-`tc replica reset --replica <name> --purge` is a partial alternative for a
+`tinycloud replica reset --replica <name> --purge` is a partial alternative for a
 named local replica only. Flag-owned purge and pending clearing have no
 equivalent yet (TC-1309). On macOS and Windows, `replica reset --purge` and
 `auth logout` with a legacy `replicas/` tree refuse local removal rather than
@@ -451,7 +458,7 @@ flag-owned replicas untouched; startup finishes the legacy removal if it is
 interrupted. If an earlier sign-out was interrupted, logout reports it and a
 second `auth logout` completes it. A gate that no longer matches its logout
 record (for example, restored from an older copy) refuses logout; switch the
-default profile if needed, then run `tc profile delete <name>` and sign in
+default profile if needed, then run `tinycloud profile delete <name>` and sign in
 again.
 
 `auth logout`, `auth rotate`, and replica-enabled `auth login` that replaces the
@@ -460,20 +467,20 @@ unexpired shares, or cannot be read, the command refuses with exit 5
 (`SHARE_HISTORY_UNEXPIRED` or `SHARE_HISTORY_UNAVAILABLE`) and changes nothing.
 Pass `--force` to proceed anyway; `auth logout --revoke` also skips the check. A
 plain re-login that keeps the key is not checked, and local-owner profiles are not
-checked. `tc share history recover` moves an unreadable history file aside to
+checked. `tinycloud share history recover` moves an unreadable history file aside to
 `share-history-v2.json.unreadable-<UTC timestamp>` and reports the new path. It
 never deletes or overwrites a file. If the file exists but cannot be read,
 recover exits 1 with `SHARE_HISTORY_RECOVER_FAILED` and moves nothing.
 
-`tc auth grants list` labels the signed-in delegation CID `(current session)`.
-`tc delegation revoke <cid>` still accepts any eligible exact CID, but when
+`tinycloud auth grants list` labels the signed-in delegation CID `(current session)`.
+`tinycloud delegation revoke <cid>` still accepts any eligible exact CID, but when
 `<cid>` is the current session it requires `--yes` or an interactive confirmation
 before contacting the node. An exact-CID success then runs the same durable
 local sign-out and key shred as `auth logout`; revoking another CID leaves the
 session intact.
 
 B-int release acceptance must
-verify the OpenKey `tc auth request --grant` fallback against a real OpenKey
+verify the OpenKey `tinycloud auth request --grant` fallback against a real OpenKey
 using a test account and no production writes: approve the request, confirm the
 grant is stored, start a fresh process, and verify the saved prefixes are
 replayed and the covered read is served locally. If OpenKey rejects explicit
@@ -481,7 +488,7 @@ replayed and the covered read is served locally. If OpenKey rejects explicit
 
 ## Output Modes
 
-`tc` auto-detects your terminal:
+`tinycloud` auto-detects your terminal:
 
 - **Interactive (TTY)** — human-friendly output with colors, tables, and status icons
 - **Piped / redirected** — structured JSON for scripting
@@ -489,29 +496,29 @@ replayed and the covered read is served locally. If OpenKey rejects explicit
 
 ```bash
 # Human-friendly table
-tc kv list
+tinycloud kv list
 
 # JSON for scripting
-tc kv list --json
-tc kv list | jq '.[]'
+tinycloud kv list --json
+tinycloud kv list | jq '.[]'
 ```
 
 ## Diagnostics
 
 ```bash
-tc doctor
+tinycloud doctor
 ```
 
 Checks Node.js version, profile configuration, keys, session status, node connectivity (with latency), and space availability. Outputs actionable guidance for any failing checks.
 
 ## Profiles
 
-`tc` supports multiple profiles for different environments:
+`tinycloud` supports multiple profiles for different environments:
 
 ```bash
-tc profile create staging --host https://staging.tinycloud.xyz
-tc profile list
-tc kv list --profile staging
+tinycloud profile create staging --host https://staging.tinycloud.xyz
+tinycloud profile list
+tinycloud kv list --profile staging
 ```
 
 ### Pointing a profile at a self-hosted OpenKey
@@ -529,7 +536,7 @@ profile JSON directly:
 }
 ```
 
-`tc auth login --method openkey` and `tc auth request` honor this for the
+`tinycloud auth login --method openkey` and `tinycloud auth request` honor this for the
 profile. Set `TC_OPENKEY_HOST` to override per invocation without editing the
 file.
 

package/bin/tinycloud

@@ -1,3 +1,12 @@
 #!/usr/bin/env node
 
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (basename(process.argv[1] ?? "") === "tc") {
+  process.stderr.write("tc is now tinycloud; tc will keep working for now.\n");
+}
+// Both installed names share one entry and canonical command/error guidance.
+process.argv[1] = fileURLToPath(import.meta.url);
+
 import("../dist/index.js");