@tinycloud/cli 1.2.0-beta.1 → 1.2.0-beta.11

package/README.md

@@ -8,17 +8,39 @@ Self-sovereign storage from the terminal. `tc` is the command-line interface for
 npm install -g @tinycloud/cli
 ```
 
-Requires Node.js >= 20. On Linux, `/usr/sbin/tc` (iproute2) can shadow this
-CLI; call it as `"$(npm prefix --global)/bin/tc"` when in doubt.
+Requires Node.js >= 20.
+
+On Linux, iproute2 installs `/usr/sbin/tc` (traffic control), which can shadow
+this CLI on PATH. 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.
 
 ## Agent skills
 
 The package ships the general `tc-cli` skill and its references in
-`skills/tc-cli`. See [skill installation](skills/tc-cli/INSTALL.md) for a
+`skills/tc-cli`, and the `courier` skill for `tc courier` in `skills/courier`.
+See [skill installation](skills/tc-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
 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
+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
+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
+```
+
 ## Operations coverage
 
 The migrated `tc secrets get` path is owned by `@tinycloud/operations` and
@@ -62,9 +84,15 @@ tc kv list
 
 # Manage network-encrypted secrets on the default network
 tc secrets network init
-tc secrets put ANTHROPIC_API_KEY "sk-..."
+printf '%s' "$ANTHROPIC_API_KEY" | tc secrets put ANTHROPIC_API_KEY --stdin
 tc secrets get ANTHROPIC_API_KEY
 
+# 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
+
 # Manage spaces
 tc space list
 tc space create
@@ -105,9 +133,13 @@ tc delegation create --to did:pkh:eip155:1:0x...
 | `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 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)) |
 
 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
@@ -124,8 +156,31 @@ network grant` takes the short name, resolves the network, and grants
 -q, --quiet             Suppress non-essential output
     --json              Force JSON output
     --no-cache          Disable caching
+    --replication       Enable read-through replication (or TC_REPLICATION=1)
+    --no-replication    Disable replication for this invocation
+    --replication-debug Write replication diagnostics to stderr
 ```
 
+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
+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
+unrestricted `get` and explicit `sync` on that folder or broader; an exact-key
+grant never qualifies. Bare replica prefixes are rejected; use `notes/`.
+Use `tc replica report` for event aggregates and pinned keys; `--clear-pending`
+prints a warning because later commits can be read as stale until a subsequent
+sync. `auth logout` removes both legacy replicas and the flag-owned
+`replication/` root; `auth logout --keep-replicas` keeps both. B-int release
+acceptance must verify the OpenKey `tc 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 `kv/get` plus `sync`, stop before release and resolve the
+protocol contract.
+
 ## Output Modes
 
 `tc` auto-detects your terminal:
@@ -185,7 +240,8 @@ file.
 | Variable | Description |
 |----------|-------------|
 | `TC_HIDE_BANNER` | Set to `1` to suppress the startup banner |
-| `TC_OPENKEY_HOST` | Override the active profile's OpenKey base URL for this invocation. |
+| `TC_REPLICATION` | Set to `1` to enable replication by default; `--no-replication` overrides it. |
+| `TC_REPLICATION_DEBUG` | Set to `1` to enable replication diagnostics on stderr. |
 
 ## Development
 

package/dist/courier-entry.d.ts

@@ -0,0 +1,3 @@
+declare function runCourier(argv: string[]): Promise<number>;
+
+export { runCourier };