@tinycloud/cli 1.5.0-beta.28 → 1.5.0-beta.29
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +148 -140
- package/bin/tinycloud +9 -0
- package/package.json +6 -6
- package/skills/{tc-cli → tinycloud-cli}/AUTH.md +15 -21
- package/skills/tinycloud-cli/INSTALL.md +36 -0
- package/skills/{tc-cli → tinycloud-cli}/REFERENCE.md +88 -94
- package/skills/{tc-cli → tinycloud-cli}/SDK.md +1 -1
- package/skills/{tc-cli → tinycloud-cli}/SKILL.md +28 -31
- package/skills/{tc-cli → tinycloud-cli}/release.json +1 -1
- package/skills/tc-cli/INSTALL.md +0 -35
|
@@ -1,45 +1,42 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
2
|
+
name: tinycloud-cli
|
|
3
3
|
description: Read, store, and share authorized TinyCloud data with the tinycloud CLI. Use for TinyCloud account/profile and space selection, permissions, device login from a phone, SQL/KV operations, publishing Share links, and installing official application guidance.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# TinyCloud CLI
|
|
7
7
|
|
|
8
|
-
Use the installed `@tinycloud/cli` executable, `tinycloud`.
|
|
8
|
+
Use the installed `@tinycloud/cli` executable, `tinycloud`. Install the pinned version from https://agents.tinycloud.xyz/cli if it is not available on PATH. Do not invoke the older `tc` name, which clashes with `/usr/sbin/tc` (iproute2 traffic control) on many Linux hosts.
|
|
9
9
|
|
|
10
10
|
```bash
|
|
11
|
-
|
|
12
|
-
[ -n "${TC_BIN:-}" ] || [ -x "$TC" ] || ! command -v npm >/dev/null || TC="$(npm prefix --global)/bin/tinycloud" # else a global npm install
|
|
13
|
-
[ -x "$TC" ] || { echo "TC_NOT_FOUND: $TC is not executable; install the CLI from https://agents.tinycloud.xyz/cli or set TC_BIN" >&2; exit 1; }
|
|
14
|
-
"$TC" --version
|
|
11
|
+
tinycloud --version
|
|
15
12
|
```
|
|
16
13
|
|
|
17
|
-
|
|
14
|
+
Run the command examples below with `tinycloud`. Node.js 20 or later runs the CLI. Check [release.json](release.json) for the CLI range this skill describes.
|
|
18
15
|
|
|
19
16
|
## Establish the context
|
|
20
17
|
|
|
21
18
|
Keep the selected profile, host and space explicit across reads and follow-ups:
|
|
22
19
|
|
|
23
20
|
```bash
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
21
|
+
tinycloud profile list
|
|
22
|
+
tinycloud --profile PROFILE context --json
|
|
23
|
+
tinycloud --profile PROFILE auth caps
|
|
27
24
|
```
|
|
28
25
|
|
|
29
26
|
`context` reports the selected profile, owner DID, host, space and local session expiry without returning keys, tokens or signed proof. `access: "not-tested"` is intentional: neither a saved session nor a listed capability proves a storage read succeeds. Verify a known authorized resource next. `auth whoami` shows both the primary owner and the local session identity; a `did:key` session is not a new owner account.
|
|
30
27
|
|
|
31
28
|
## Sign in
|
|
32
29
|
|
|
33
|
-
To set up a new owner (no profile, or no TinyCloud account yet), run `
|
|
30
|
+
To set up a new owner (no profile, or no TinyCloud account yet), run `tinycloud onboard`. It creates the profile and waits for two OpenKey approvals in sequence: the owner's sign-in (or new account) with read and write on the `applications` space, then read-only `spaces/` and `applications/` in the `account` space, each for 30 days. Keep the command running and send the owner each short approval link as it appears on stderr. No return code or localhost callback is needed. Stdout has no pending JSON; successful completion prints JSON with `"onboarded": true` and exits 0. After an interruption, re-run the same command to resume its pending approval and retain the saved applications step. The step-by-step guide for agents is https://agents.tinycloud.xyz/onboarding.
|
|
34
31
|
|
|
35
32
|
Agents can use normal OpenKey login with `--no-popup` and relay its stderr approval link to the owner, even without a local browser or terminal. Device login is an optional alternative for eligible permission manifests. Read [AUTH.md](AUTH.md) before the first login; the automatic short-link flow and the device or manual-code alternatives have different approval windows.
|
|
36
33
|
|
|
37
34
|
Use a new profile name if it already exists. Keep the user's existing profiles: another app's session may live there, and a login for a different purpose would drop it (the CLI refuses with `SESSION_IN_USE`). Publish from a dedicated profile:
|
|
38
35
|
|
|
39
36
|
```bash
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
37
|
+
tinycloud profile list # pick an unused name
|
|
38
|
+
tinycloud init --name publisher --key-only
|
|
39
|
+
tinycloud --profile publisher auth login --device --manifest builtin:share-publishing
|
|
43
40
|
```
|
|
44
41
|
|
|
45
42
|
`builtin:share-publishing` covers `tinycloud share publish`. Device login carries KV-scoped manifests plus the `tinycloud.capabilities/read` entry on path `""` that OpenKey requires to sign (the built-in manifest includes it; an app manifest without it is refused with `SCOPE_REJECTED`). OpenKey also refuses `tinycloud.sql` (and other abilities its device policy excludes) with `SCOPE_REJECTED`. For app data that needs SQL, the owner signs in through the browser with the app's manifest instead (see [AUTH.md](AUTH.md)). For an existing app account, the owner approves with their existing OpenKey identity; do not create another account.
|
|
@@ -51,10 +48,10 @@ SQL commands need a profile whose session the owner granted through browser logi
|
|
|
51
48
|
To read a KV prefix while the host is unreachable, keep a local replica: `tinycloud replica sync --prefix PREFIX` under a device grant with `sync`, then `tinycloud replica get|list` read only local storage. See [REFERENCE.md](REFERENCE.md#local-replicas) for the grant flow, expiry and exit codes.
|
|
52
49
|
|
|
53
50
|
```bash
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
51
|
+
tinycloud --profile PROFILE kv get KEY --space SPACE --json
|
|
52
|
+
tinycloud --profile PROFILE kv get KEY --space SPACE --raw -o ./resource.txt
|
|
53
|
+
tinycloud --profile PROFILE kv list --space SPACE --prefix PREFIX --all --json
|
|
54
|
+
tinycloud --profile PROFILE sql query 'SELECT id, body FROM records WHERE id = ?' --space SPACE --db DATABASE --params '["record-id"]' --json
|
|
58
55
|
```
|
|
59
56
|
|
|
60
57
|
Use literal subprocess arguments and SQL parameters for values. `tinycloud` has no generic content-search index. `kv list` returns one page unless you pass `--all`. Its JSON reports `truncated` and `nextCursor` (`null` when the node doesn't say), and `--limit N --cursor C` reads page by page. Claim a complete listing only when `truncated` is `false`. If output is large, read to a local file and account for every returned portion before claiming full coverage. A metadata row or summary is not the original body.
|
|
@@ -68,15 +65,15 @@ Tiny apps keep their code and data in the user's `applications` space, one `<app
|
|
|
68
65
|
Ask for the narrowest grant that does the job. The default is read-only, and one app is safer than all of them. The agent makes the request, the owner approves it, the agent imports the result:
|
|
69
66
|
|
|
70
67
|
```bash
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
68
|
+
tinycloud --profile agent profile create agent --posture delegate-session --operator agent # once
|
|
69
|
+
tinycloud --profile agent auth request --preset apps-agent --app APP_ID --emit req.json # read-only; prints the scope in plain words
|
|
70
|
+
tinycloud --profile owner auth grant req.json > grant.json # the owner approves
|
|
71
|
+
tinycloud --profile agent auth import grant.json
|
|
75
72
|
```
|
|
76
73
|
|
|
77
74
|
- `--preset apps-agent` is **read-only**: KV get and list, SQL read, on the `applications` space, up to 7 days. That is enough to pick up where the user left off by reading `knowledge/*` and querying the data. The node refuses a KV put or a SQL write under it.
|
|
78
75
|
- `--app APP_ID` limits it to `APP_ID/` and is the recommended default. Repeat `--app` (up to 5) for a task that spans apps. Leave it off only to read every installed app; the command says so before the owner approves.
|
|
79
|
-
- **Write access only when the owner asks to change an installed app's data** (for example, log a meal). The agent requests it from its own profile with one command: `
|
|
76
|
+
- **Write access only when the owner asks to change an installed app's data** (for example, log a meal). The agent requests it from its own profile with one command: `tinycloud --profile agent auth request --preset apps-agent --app APP_ID --write --emit req.json`. The owner approves it in OpenKey, then the agent imports the grant as above. `--write` needs `--app`. The grant lasts as long as the owner's approval allows, up to 7 days.
|
|
80
77
|
- With `--write`, the agent can add and change that app's data: it writes files under `APP_ID/knowledge/` and `APP_ID/prefs/` and adds, changes and deletes its table rows. It can create, change or drop tables only in the catalog database of a catalog app (for example `xyz.tinycloud.sample.healthlog/healthlog`), and the grant names no other database for that; nodes before 1.21.6 do not enforce this limit, so an ad-hoc CREATE, ALTER or DROP needs the owner's confirmation first. It cannot change the app's code, its manifest or its install record, and every other file under `APP_ID/` stays read-only. It cannot touch other apps, other spaces or secrets.
|
|
81
78
|
- For a catalog app's write access, go straight to `auth request`: the owner's one OpenKey approval is the consent, so do not ask the owner again before requesting. The grant covers one named app: never ask for the whole space, and never a write without `--app`.
|
|
82
79
|
- The preset cannot be combined with `--cap`, `--permission`, `--manifest` or `--expiry`, and device approval cannot grant it (SQL needs browser or `--paste`). The owner ends the grant with `tinycloud delegation revoke GRANT_CID`; the CID is in the `auth grant` output. Within its own grant the agent's key could pass the same access on to someone else, so keep the key and the grant file private.
|
|
@@ -86,8 +83,8 @@ Ask for the narrowest grant that does the job. The default is read-only, and one
|
|
|
86
83
|
|
|
87
84
|
Then:
|
|
88
85
|
|
|
89
|
-
1. `
|
|
90
|
-
2. `
|
|
86
|
+
1. `tinycloud --profile agent knowledge list` (add `--app APP_ID` under a one-app grant) lists the apps that have a bundle: `app_id`, `name` when the account registry is readable, `root`, `concepts`. MCP: `tinycloud_knowledge_list`.
|
|
87
|
+
2. `tinycloud --profile agent knowledge read APP_ID` reads the index: its links name the concepts. Then `knowledge read APP_ID app` (what the app is and its write rules), and only the concepts the task needs, such as `knowledge read APP_ID tables/meal`. Frontmatter comes back parsed. MCP: `tinycloud_knowledge_read`.
|
|
91
88
|
3. A concept's `resource:` is a space-relative cap without actions, such as `tinycloud.sql:applications:APP_ID/health_log` with `table: meal`, or `tinycloud.kv:applications:APP_ID/photos/`. Use it as the target of `sql query` (`--db` is the path after the space) and `kv get` (the path is the key prefix), with `--space` set to the `space` URI that `knowledge list` printed: a bare `applications` fails on an agent profile. Pass the cap to `--cap` unchanged to ask for more.
|
|
92
89
|
4. Only with a write grant: `app.md` holds the app's write rules (required columns, allowed values, ids). Follow them exactly, write only under `APP_ID/`, and run an ad-hoc CREATE, ALTER or DROP only after the owner confirms the structural change. The grant covers those statements only in the app's catalog database. Nodes before 1.21.6 do not enforce that, so the agent keeps its own statements inside that database.
|
|
93
90
|
5. Record what you did in `APP_ID/knowledge/log.md` when `app.md` says to (needs the write grant).
|
|
@@ -98,21 +95,21 @@ Exit code 5 from `knowledge list|read` means the grant does not cover that app;
|
|
|
98
95
|
|
|
99
96
|
An agent installs a catalog app into its own profile. The owner approves the agent's write grant for that one app; the install then runs under that grant without a second approval:
|
|
100
97
|
|
|
101
|
-
1. `
|
|
102
|
-
2. `
|
|
98
|
+
1. `tinycloud --profile agent auth request --preset apps-agent --write --app xyz.tinycloud.sample.healthlog --emit req.json`. The owner approves it in OpenKey, then the agent imports the grant as above (`auth import`).
|
|
99
|
+
2. `tinycloud --profile agent apps install xyz.tinycloud.sample.healthlog` installs the pinned version into the owner's applications space, through the grant. Then read the notes with `knowledge read`.
|
|
103
100
|
|
|
104
101
|
The install fetches each file from Share by its pinned digest and checks size and sha256 before any write. The pinned DDL runs only if every statement is one of the installer's own (`CREATE TABLE/INDEX/VIEW IF NOT EXISTS`, and `DROP VIEW IF EXISTS` for the pinned views); any other statement, including `DROP TABLE`, aborts before a write. The knowledge files under `APP_ID/knowledge/` are created create-only with `index.md` last, then the schema is applied and the pinned views are re-created on every run (`viewsRecreated`).
|
|
105
102
|
|
|
106
|
-
The allowlist covers only the installer's own statements. On nodes before 1.21.6 the grant does not limit the agent's SQL to data statements, so an ad-hoc CREATE, ALTER or DROP outside the install still needs the owner's confirmation first (see the write-access bullets under "Pick up a user's apps"). The owner can run the same command on the owner profile (`
|
|
103
|
+
The allowlist covers only the installer's own statements. On nodes before 1.21.6 the grant does not limit the agent's SQL to data statements, so an ad-hoc CREATE, ALTER or DROP outside the install still needs the owner's confirmation first (see the write-access bullets under "Pick up a user's apps"). The owner can run the same command on the owner profile (`tinycloud --profile owner apps install xyz.tinycloud.sample.healthlog`); that needs no grant.
|
|
107
104
|
|
|
108
105
|
Knowledge files whose bytes differ from the pinned version are left as the owner edited them and listed (`conflicts` in `--json`). That is not an error: the command exits 0 and installs everything else. If the schema fails after notes were written, the command says "notes saved; tables not set up: run again" and exits non-zero; running it again is safe.
|
|
109
106
|
|
|
110
107
|
## Publish and share
|
|
111
108
|
|
|
112
109
|
```bash
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
110
|
+
tinycloud --profile publisher share publish ./note.md --json
|
|
111
|
+
tinycloud --profile publisher share publish ./note.md --to email:alice@example.com --notify --json
|
|
112
|
+
tinycloud --profile publisher share publish ./site/ --json # a folder with a top-level index.html -> one self-contained page
|
|
116
113
|
```
|
|
117
114
|
|
|
118
115
|
A folder (a top-level `index.html` plus the CSS, scripts, images and fonts it uses) is inlined into one self-contained `.html` and published as an anyone-with-the-link share named `<folder>.html` (or `--name`). Use only files in the folder: external URLs, frames, forms, `<base>`, module scripts and links to other pages are refused, with an error that names the file and the reference (`UNSUPPORTED_HTML`, `HTML_RESOURCE_MISSING`, `UNSAFE_PATH`, `UNSUPPORTED_FOLDER_ENTRY`, `MAX_BYTES_EXCEEDED`), and nothing is published. Symbolic links are refused, entries starting with `.` are skipped, and `manifest.json` and `knowledge/` are not inlined or published. Folders cannot be shared to an address or with `--prefix`; publish a single file for those.
|
package/skills/tc-cli/INSTALL.md
DELETED
|
@@ -1,35 +0,0 @@
|
|
|
1
|
-
# Install, update and remove the core skills
|
|
2
|
-
|
|
3
|
-
agents.tinycloud.xyz serves every TinyCloud skill and pins the CLI version they're tested with. Install, update and remove the CLI and the `tc-cli` and `courier` skills from there.
|
|
4
|
-
|
|
5
|
-
## Install
|
|
6
|
-
|
|
7
|
-
Follow https://agents.tinycloud.xyz/cli. It installs the pinned TinyCloud CLI into `~/.local/share/tinycloud/cli` and installs this skill. Run the CLI as `tinycloud`, which needs CLI 1.2.3 or later; `tc` is its older name, and on many Linux hosts `tc` on `PATH` is iproute2's `/usr/sbin/tc` instead. The skill's first block finds the CLI there; set `TC_BIN` to use another one.
|
|
8
|
-
|
|
9
|
-
To install this skill, or `courier` for `tinycloud courier`, without the guide:
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
curl -fsSL https://agents.tinycloud.xyz/skills/install.js | node - cli --agent claude-code
|
|
13
|
-
curl -fsSL https://agents.tinycloud.xyz/skills/install.js | node - courier --agent claude-code
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
Use `--agent codex` or `--agent opencode` for those clients. Skills go into `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/<name>` for Claude Code and `~/.agents/skills/<name>` for Codex and OpenCode, which share that folder. The installer checks every file against https://agents.tinycloud.xyz/skills/index.json before it writes anything, and prints `SKILL_INSTALLED <name> <version> <folder>`. Start a new session for the client to discover the skill.
|
|
17
|
-
|
|
18
|
-
## Check
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
TC="${TC_BIN:-$HOME/.local/share/tinycloud/cli/node_modules/.bin/tinycloud}" # TC_BIN, else where agents.tinycloud.xyz/cli installs it
|
|
22
|
-
[ -n "${TC_BIN:-}" ] || [ -x "$TC" ] || ! command -v npm >/dev/null || TC="$(npm prefix --global)/bin/tinycloud" # else a global npm install
|
|
23
|
-
[ -x "$TC" ] || { echo "TC_NOT_FOUND: $TC is not executable; install the CLI from https://agents.tinycloud.xyz/cli or set TC_BIN" >&2; exit 1; }
|
|
24
|
-
"$TC" --version
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
The installed `tc-cli/release.json` names the CLI range the skill describes. Check it against the version before relying on newer commands. App skills publish their own CLI compatibility.
|
|
28
|
-
|
|
29
|
-
## Update
|
|
30
|
-
|
|
31
|
-
Run the install again. It installs the versions agents.tinycloud.xyz serves, which change only when the site's pins change; it never follows an npm dist-tag.
|
|
32
|
-
|
|
33
|
-
## Remove
|
|
34
|
-
|
|
35
|
-
Delete the skill folders: `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/tc-cli` and `courier` for Claude Code, `~/.agents/skills/tc-cli` and `courier` for Codex and OpenCode. To remove the CLI, delete the `tc` or `tinycloud` link the setup made, if it points into `~/.local/share/tinycloud/cli`, then that folder. Removing the skill or CLI doesn't delete TinyCloud profiles or revoke data access.
|