noeta-cli 0.1.0 → 0.1.1

package/AGENTS.md

@@ -0,0 +1,72 @@
+# Using `noeta-cli` (for coding agents)
+
+You are an agent with shell access. `noeta-cli` is a portal to a **Noeta Cloud** workspace —
+read, write, edit, and find documents (and tables, comments, chat) from the command line, with
+**no MCP client configuration**. This file is the playbook; the CLI itself is the live reference.
+
+## The loop: authenticate → discover → act
+
+```bash
+# 1. AUTHENTICATE (once per machine/deployment). Opens the user's browser to approve; finishes
+#    on their click. If you're headless, add --no-open: login prints BOTH a direct link and a
+#    short code + /activate URL — hand either to the user. They can approve on any already-signed-in
+#    device (e.g. their phone) by typing the code at /activate. Nothing is emailed.
+npx noeta-cli login                      # defaults to https://noeta.cloud
+npx noeta-cli whoami                      # confirm identity + which workspace + your access cap
+
+# 2. DISCOVER the tool surface + exact argument schemas (authoritative — do this, don't guess):
+npx noeta-cli tools                       # names + one-line descriptions
+npx noeta-cli tools --json                # full JSON with inputSchema for every tool
+
+# 3. ACT — every tool is `call <name> '<json-args>'`:
+npx noeta-cli call <tool> '{"...":"..."}'
+```
+
+Installed globally (`npm i -g noeta-cli`) the command is just `noeta`; `npx noeta-cli` always
+works with no install. Everything below uses `noeta`.
+
+## Finding, reading, writing, editing documents
+
+The tool set is discovered at runtime (`noeta tools --json`) — treat that as SSOT, not this list.
+As of writing the verbs map like so:
+
+| Intent | Tool(s) | Notes |
+|---|---|---|
+| **Find** a doc/folder/table | `list_resources`, `get_related` | Browse the workspace tree; get the `docId` you need |
+| **Read** a doc | `get_doc` | Returns the block tree (ids, types, content). **Call this first** — edits target block ids |
+| **Create** a doc / folder | `create_doc`, `create_folder` | New document or folder; pass `parentId` to nest (else workspace root) |
+| **Write** into a doc | `insert_blocks` | Append, or place `afterId`/`beforeId` a block id from `get_doc` |
+| **Edit** a block | `update_block` | Change a block's type/props/content by id |
+| **Delete** blocks | `remove_blocks` | By id; ids already gone are skipped, not errors |
+| **Organize** | `move_resource` | Move a doc/folder into a folder (or to root with `parentId: null`); needs editor on both ends |
+| **Share** with a member/team | `share_resource` | Grant an existing member (`user`) or team (`group`) a role; needs **manager** on the resource |
+| **Invite an outsider** | `invite_guest` | Invite someone by email to a SINGLE resource as a scoped guest (no workspace-wide access); needs **manager**. Sends an invite email; the grant applies when they accept |
+| Comment / versions / chat / tables | `comment`, `list_versions`, `restore_version`, `post_message`, `get_thread`, table ops | See `noeta tools --json` |
+
+Typical edit session:
+
+```bash
+noeta call list_resources '{}'                                  # find the doc, note its id
+noeta call get_doc '{"docId":"<id>"}'                           # read block tree, pick target ids
+noeta call insert_blocks '{"docId":"<id>","blocks":[{"type":"paragraph","content":"…"}]}'
+noeta call update_block  '{"docId":"<id>","id":"<blockId>","block":{"content":"revised"}}'
+```
+
+## The agent contract
+
+- **No command reads stdin** — safe to run noninteractively.
+- `--json` makes **stdout a single machine-readable value**; all progress/errors go to **stderr**.
+- **Exit codes:** `0` ok · `1` usage/network/server error · `2` login denied/expired/timed out ·
+  `3` the tool call itself returned an error (reason on stderr). Branch on these, not on parsing text.
+- **Target/token resolution:** `--url` flag > `NOETA_URL` > last login; token `NOETA_TOKEN` > stored.
+  Credentials live in `~/.config/noeta/credentials.json` (override dir with `NOETA_CONFIG_DIR`).
+
+## What your identity is (and safety)
+
+Approving mints a **delegated identity**: you act on the approving user's behalf, capped at the
+access level they picked — you can do at most what they can, and everything you write is attributed
+to them *via* the agent. There's no separate secret to manage. The user can revoke you any time
+(`noeta logout`, or `DELETE /api/agents/<id>` as themselves). Prefer read tools when exploring;
+only write when the task calls for it.
+
+Full human reference: `README.md` in this package, or `noeta help`.

package/README.md

@@ -15,6 +15,12 @@ finishes on the click — it never asks for terminal input — and saves the tok
 locally. From then on the CLI *is* the integration; no MCP client
 configuration required:
 
+**No browser on this machine?** (a server, an SSH session, a container.) `login`
+also prints a short code and an `/activate` URL. On any device that's already
+signed in — your phone, say — go to `https://noeta.cloud/activate`, type the
+code, and approve there. Nothing is emailed; you initiate it from the terminal
+and confirm on a device you're already logged into.
+
 ```bash
 npx noeta-cli whoami                              # who am I, which workspace, what cap
 npx noeta-cli tools                               # list the workspace's tools
@@ -39,6 +45,9 @@ signed-in user).
 
 ## For agents driving this programmatically
 
+**Coding agent?** Read [`AGENTS.md`](./AGENTS.md) — the playbook for driving this from a shell
+(authenticate → `noeta tools --json` to discover → `noeta call`). The short version:
+
 No command reads stdin, and `--json` makes stdout a single machine-readable
 value (progress and errors go to stderr):
 

package/cli.mjs

@@ -162,11 +162,20 @@ async function cmdLogin() {
 
   const startRes = await post(baseUrl, "/api/agent-auth/start", { clientName: opts.name });
   if (!startRes.ok) die(`start failed: HTTP ${startRes.status} ${await startRes.text()}`);
-  const { deviceCode, verifyUrl, expiresIn, interval } = await startRes.json();
+  const { deviceCode, verifyUrl, activateUrl, userCode, expiresIn, interval } = await startRes.json();
 
   const windowSec = Number.isFinite(opts.timeout) && opts.timeout > 0 ? opts.timeout : expiresIn;
-  log(`\nAuthorize ${opts.name} in your browser (link expires in ${Math.round(expiresIn / 60)} min):\n`);
-  log(`\n  ${verifyUrl}\n\n`);
+  const mins = Math.round(expiresIn / 60);
+  // Group the short code as XXXX-XXXX so it's easy to read off one screen and type on another.
+  const grouped = userCode ? userCode.replace(/(.{4})(?=.)/g, "$1-") : null;
+  log(`\nAuthorize ${opts.name} (expires in ${mins} min):\n`);
+  if (activateUrl && grouped) {
+    // Cross-device path (e.g. approve on your phone): type the code at /activate.
+    log(`\n  • This machine — your browser should open; if not, visit:\n      ${verifyUrl}\n`);
+    log(`\n  • Another device already signed in (e.g. your phone):\n      go to   ${activateUrl}\n      enter   ${grouped}\n\n`);
+  } else {
+    log(`\n  ${verifyUrl}\n\n`);
+  }
   if (opts.open) openBrowser(verifyUrl);
   log("Waiting for approval…");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "noeta-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI portal to Noeta Cloud for agents & humans: `npx noeta-cli login` (browser approval, no prompts), then call the workspace API/MCP tools directly — no MCP client configuration required.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "cli.mjs",
-    "README.md"
+    "README.md",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=18"