@octonote/cli 0.0.0-stage → 0.1.4

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @octonote/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`octonote` — Octonote from your terminal, built for **AI agents** (Claude Code,
+Codex) as much as for people. Write notes from markdown, draw canvases from
+mermaid flowcharts, organise them in notebooks, publish and share — all
+through the same API the app uses, with your permissions.
+
+```bash
+npm i -g @octonote/cli && octonote   # installs, then shows getting started
+octonote login                 # opens the browser; click Authorize
+octonote setup claude          # or: octonote setup codex — teaches your agent
+```
+
+Full docs — every command, Claude Code & Codex setup, troubleshooting:
+**https://octonote.ai/cli**
+
+Then just ask your agent: *“Write up the auth flow in my Architecture notebook,
+with a diagram, and publish it.”*
+
+## For agents
+
+`octonote guide` prints everything an agent needs in one read. In short:
+
+- JSON output when piped; errors are `{"error":{"code","message","hint"}}`
+  with a non-zero exit code (2 usage, 3 not signed in, 4 not found, 5 plan
+  limit, 6 network).
+- Never prompts. Content comes from `--file`, `--stdin` or `-`.
+- Every result carries `id`, `url` and (once published) `publicUrl`.
+
+## Commands
+
+```
+octonote login | logout | whoami | workspace list|use | token list|revoke
+octonote note create|show|pull|push|append|rename
+octonote canvas create [--from-mermaid f.mmd | --file c.json] | redraw | pull | push
+octonote project create <name> --note doc.md --canvas-mermaid flow.mmd | show
+octonote notebook list|create|show
+octonote list | search | open | move | delete --yes
+octonote publish | unpublish | share --email … --role viewer|editor | share --link view|edit|off
+octonote guide | setup claude|codex [--global] [--skill]
+```
+
+## Without a browser (CI, cloud agents)
+
+Create a token in **Settings → CLI & agents → Create token** and set it as
+`OCTONOTE_TOKEN`. Tokens can do what you can do in the app, except create
+more tokens or delete your account; revoke them any time in Settings.
+
+| Variable | Default |
+|---|---|
+| `OCTONOTE_TOKEN` | sign-in from `octonote login` |
+| `OCTONOTE_WORKSPACE` | the workspace you own |
+| `OCTONOTE_API_URL` / `OCTONOTE_WEB_URL` | hosted Octonote |
+| `OCTONOTE_CONFIG_DIR` | `~/.octonote` |

package/dist/commands/agents.js

@@ -0,0 +1,71 @@
+/**
+ * Teaching agents the CLI: `octonote guide` prints the guide; `octonote
+ * setup claude|codex` writes a short section into the project's CLAUDE.md
+ * or AGENTS.md (between markers, so re-running updates it in place) and,
+ * for Claude, can install a skill.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { usage } from "../core/errors.js";
+import { emit } from "../core/output.js";
+import { action } from "../core/run.js";
+import { AGENT_GUIDE, CLAUDE_SKILL, PROJECT_SECTION, } from "../guide/agent-guide.js";
+const START = "<!-- octonote:start -->";
+const END = "<!-- octonote:end -->";
+/** Insert or replace the marked Octonote section; returns the new text. */
+export function upsertSection(existing, section) {
+    const block = `${START}\n${section.trim()}\n${END}`;
+    const re = new RegExp(`${START}[\\s\\S]*?${END}`);
+    if (re.test(existing))
+        return existing.replace(re, block);
+    const sep = existing.trim() ? `${existing.replace(/\s*$/, "")}\n\n` : "";
+    return `${sep}${block}\n`;
+}
+async function readOr(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+async function write(path, text) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, text);
+}
+export function registerAgents(program) {
+    program
+        .command("guide")
+        .description("Print the usage guide for AI agents (Claude Code, Codex, …)")
+        .action(action(async () => {
+        // Plain text even when piped: agents read it as instructions.
+        process.stdout.write(AGENT_GUIDE);
+    }, { auth: false }));
+    program
+        .command("setup")
+        .description("Teach an agent to use Octonote: writes a section into CLAUDE.md (claude) or AGENTS.md (codex)")
+        .argument("<agent>", "claude | codex")
+        .option("--dir <path>", "project folder", ".")
+        .option("--global", "for every project: ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md")
+        .option("--skill", "claude only: also install the Octonote skill (.claude/skills/octonote)")
+        .action(action(async (_ctx, agent, opts) => {
+        const which = agent.toLowerCase();
+        if (which !== "claude" && which !== "codex")
+            throw usage(`Unknown agent "${agent}".`, "Use claude or codex.");
+        if (opts.skill && which !== "claude")
+            throw usage("--skill is for Claude Code only.");
+        const base = opts.global
+            ? join(homedir(), which === "claude" ? ".claude" : ".codex")
+            : resolve(opts.dir);
+        const file = join(base, which === "claude" ? "CLAUDE.md" : "AGENTS.md");
+        await write(file, upsertSection(await readOr(file), PROJECT_SECTION));
+        const written = [file];
+        if (opts.skill) {
+            const skill = join(opts.global ? join(homedir(), ".claude") : join(base, ".claude"), "skills/octonote/SKILL.md");
+            await write(skill, CLAUDE_SKILL);
+            written.push(skill);
+        }
+        emit({ agent: which, files: written }, (d) => `Updated:\n${d.files.map((f) => `  ${f}`).join("\n")}\n${which === "claude" ? "Claude Code" : "Codex"} will now use Octonote when you ask.`);
+    }, { auth: false }));
+}

package/dist/commands/auth.js

@@ -0,0 +1,155 @@
+import { customUrl, DEFAULT_API_URL, DEFAULT_WEB_URL, readStored, writeStored, } from "../core/config.js";
+import { CliError, usage } from "../core/errors.js";
+import { ApiClient } from "../core/http.js";
+import { readStdin } from "../core/input.js";
+import { browserLogin, TOKEN_RE } from "../core/login.js";
+import { emit, info, table } from "../core/output.js";
+import { action } from "../core/run.js";
+export function registerAuth(program) {
+    program
+        .command("login")
+        .description("Sign in through the browser (or --paste a token from Settings → CLI & agents)")
+        .option("--paste", "read a token from stdin instead of opening the browser")
+        .action(action(async (ctx, opts) => {
+        let token;
+        if (opts.paste) {
+            token = (await readStdin()).trim();
+            if (!TOKEN_RE.test(token))
+                throw usage("That isn't an Octonote token (they start with ont_).");
+        }
+        else {
+            if (!process.stdout.isTTY && !process.stderr.isTTY) {
+                throw usage("`octonote login` needs a person at a browser.", "Agents and CI: set OCTONOTE_TOKEN (Settings → CLI & agents → Create token), or pipe one into `octonote login --paste`.");
+            }
+            ({ token } = await browserLogin({
+                webUrl: ctx.config.webUrl,
+                onUrl: (url) => {
+                    process.stderr.write(`Opening your browser to connect the CLI…\nIf it doesn't open, visit:\n  ${url}\n`);
+                    if (process.stdin.isTTY)
+                        process.stderr.write("…or paste a token here and press Enter.\n");
+                },
+            }));
+        }
+        // Check the token works before saving it.
+        const me = await new ApiClient({
+            apiUrl: ctx.config.apiUrl,
+            token,
+        }).get("/me");
+        // Addresses are saved only when custom (e.g. a local stack), so
+        // everyone else follows the defaults if hosting ever moves.
+        await writeStored({
+            token,
+            email: me.user.email,
+            apiUrl: customUrl(ctx.config.apiUrl, DEFAULT_API_URL),
+            webUrl: customUrl(ctx.config.webUrl, DEFAULT_WEB_URL),
+        });
+        emit({ signedIn: true, email: me.user.email }, () => `✓ Signed in as ${me.user.email}`);
+        info("\nNext: teach your agent to use Octonote —\n  octonote setup claude          (or: octonote setup claude --global --skill)\n  octonote setup codex\nRun `octonote` for the full getting-started screen.");
+        if (ctx.config.tokenSource === "env")
+            info("Note: OCTONOTE_TOKEN is set and takes precedence over this sign-in.");
+    }, { auth: false }));
+    program
+        .command("logout")
+        .description("Sign out here and revoke this computer's token")
+        .action(action(async (ctx) => {
+        const stored = await readStored();
+        if (stored.token) {
+            // Best effort: the token is forgotten locally either way.
+            await ctx.api
+                .delete("/me/cli-tokens/current")
+                .catch(() => undefined);
+        }
+        await writeStored({
+            token: undefined,
+            email: undefined,
+            workspaceId: undefined,
+        });
+        emit({ signedOut: true }, () => "Signed out.");
+    }, { auth: false }));
+    program
+        .command("whoami")
+        .description("Who you're signed in as, and which workspace commands use")
+        .action(action(async (ctx) => {
+        const me = await ctx.me();
+        const ws = await ctx.workspaceId();
+        const workspace = me.memberships.find((m) => m.workspace.id === ws)?.workspace;
+        emit({
+            email: me.user.email,
+            name: me.user.name,
+            workspace: workspace
+                ? { id: workspace.id, name: workspace.name }
+                : null,
+            tokenSource: ctx.config.tokenSource,
+            apiUrl: ctx.config.apiUrl,
+            webUrl: ctx.config.webUrl,
+        }, (d) => `${d.name} <${d.email}>\nworkspace: ${d.workspace?.name ?? "—"} (${d.workspace?.id ?? ""})\nsigned in via: ${d.tokenSource === "env" ? "OCTONOTE_TOKEN" : "octonote login"}`);
+    }));
+    const account = program
+        .command("account")
+        .description("Your Octonote account");
+    account
+        .command("rename")
+        .description("Change your display name (shown in the app and as the author of pages you publish)")
+        .argument("<name>", "new display name, 1–80 characters")
+        .action(action(async (ctx, name) => {
+        const trimmed = name.trim().replace(/\s+/g, " ");
+        if (!trimmed || trimmed.length > 80) {
+            throw usage("A name needs 1–80 characters.");
+        }
+        const user = await ctx.api.patch("/me", { name: trimmed });
+        emit({ name: user.name, email: user.email }, (d) => `Your name is now ${d.name}`);
+    }));
+    const workspace = program
+        .command("workspace")
+        .description("Choose which workspace commands work in");
+    workspace
+        .command("list")
+        .description("Workspaces you belong to")
+        .action(action(async (ctx) => {
+        const me = await ctx.me();
+        const current = await ctx.workspaceId();
+        const rows = me.memberships.map((m) => ({
+            id: m.workspace.id,
+            name: m.workspace.name,
+            role: m.membership.role.toLowerCase(),
+            current: m.workspace.id === current,
+        }));
+        emit(rows, (list) => table(list.map((r) => ({ ...r, current: r.current ? "←" : "" })), ["id", "name", "role", "current"]));
+    }));
+    workspace
+        .command("use")
+        .description("Use this workspace from now on (id or exact name)")
+        .argument("<workspace>", "workspace id or name")
+        .action(action(async (ctx, ref) => {
+        const me = await ctx.me();
+        const match = me.memberships.find((m) => m.workspace.id === ref ||
+            m.workspace.name.toLowerCase() === ref.toLowerCase());
+        if (!match)
+            throw new CliError(`You're not in a workspace called "${ref}".`, "NOT_FOUND", { hint: "`octonote workspace list` shows yours." });
+        await writeStored({ workspaceId: match.workspace.id });
+        emit({ workspace: { id: match.workspace.id, name: match.workspace.name } }, (d) => `Now using ${d.workspace.name}`);
+    }));
+    const token = program
+        .command("token")
+        .description("Your CLI tokens (create new ones in Settings → CLI & agents)");
+    token
+        .command("list")
+        .description("List your tokens")
+        .action(action(async (ctx) => {
+        const rows = await ctx.api.get("/me/cli-tokens");
+        emit(rows, (list) => table(list.map((t) => ({
+            id: t.id,
+            name: t.name,
+            token: t.preview,
+            "last used": t.lastUsedAt?.slice(0, 10) ?? "never",
+        })), ["id", "name", "token", "last used"]));
+    }));
+    token
+        .command("revoke")
+        .description("Revoke a token")
+        .argument("<id>", "token id (tok_…)")
+        .action(action(async (ctx, id) => {
+        await ctx.api.delete(`/me/cli-tokens/${id}`);
+        emit({ id, revoked: true }, () => `Revoked ${id}`);
+    }));
+}

package/dist/commands/canvas.js

@@ -0,0 +1,102 @@
+import { writeFile } from "node:fs/promises";
+import { resolveNotebook } from "../core/context.js";
+import { usage } from "../core/errors.js";
+import { readContent } from "../core/input.js";
+import { emit } from "../core/output.js";
+import { parseRef } from "../core/refs.js";
+import { describeItem, item, setPublished } from "../core/resources.js";
+import { action } from "../core/run.js";
+function parseSnapshot(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        throw usage("That file isn't JSON.", "`canvas push` takes a tldraw snapshot from `canvas pull`; to draw from a diagram use --from-mermaid.");
+    }
+    if (!doc ||
+        typeof doc !== "object" ||
+        !("store" in doc) ||
+        !("schema" in doc)) {
+        throw usage("That JSON isn't a tldraw snapshot (it needs `store` and `schema`).");
+    }
+    return doc;
+}
+export function registerCanvas(program) {
+    const canvas = program
+        .command("canvas")
+        .description("Canvases: draw them from mermaid flowcharts, or push tldraw JSON");
+    canvas
+        .command("create")
+        .description("Create a canvas — drawn from a mermaid flowchart, from tldraw JSON, or empty")
+        .argument("[title]", "title", "Untitled canvas")
+        .option("-m, --from-mermaid <path>", 'mermaid flowchart file ("-" for stdin) to draw as real shapes')
+        .option("-f, --file <path>", "tldraw snapshot JSON (from `canvas pull`)")
+        .option("-n, --notebook <notebook>", "put it in a notebook (id or exact name)")
+        .option("--publish", "publish it to the web and print the public URL")
+        .action(action(async (ctx, title, opts) => {
+        if (opts.fromMermaid && opts.file)
+            throw usage("Use either --from-mermaid or --file, not both.");
+        const mermaid = opts.fromMermaid
+            ? await readContent({ file: opts.fromMermaid })
+            : null;
+        const document = opts.file
+            ? parseSnapshot((await readContent({ file: opts.file })) ?? "")
+            : null;
+        const notebookId = opts.notebook
+            ? (await resolveNotebook(ctx, opts.notebook)).id
+            : undefined;
+        const ws = await ctx.workspaceId();
+        let row = await ctx.api.post(`/workspaces/${ws}/canvases`, {
+            title: title.slice(0, 120),
+            ...(notebookId ? { notebookId } : {}),
+            ...(mermaid?.trim() ? { mermaid } : {}),
+        });
+        if (document)
+            row = await ctx.api.patch(`/canvases/${row.id}`, {
+                document,
+            });
+        const out = item(ctx, "canvas", row);
+        if (opts.publish)
+            out.publicUrl = (await setPublished(ctx, "canvas", row.id, true)).publicUrl;
+        emit(out, describeItem);
+    }));
+    canvas
+        .command("redraw")
+        .description("Replace a canvas with a drawing of a mermaid flowchart")
+        .argument("<canvas>", "canvas id (cnv_…) or URL")
+        .requiredOption("-m, --from-mermaid <path>", 'mermaid flowchart file ("-" for stdin)')
+        .action(action(async (ctx, ref, opts) => {
+        const { id } = parseRef(ref, "canvas");
+        const mermaid = (await readContent({ file: opts.fromMermaid })) ?? "";
+        const row = await ctx.api.put(`/canvases/${id}/mermaid`, {
+            mermaid,
+        });
+        emit(item(ctx, "canvas", row), (i) => `Redrew ${describeItem(i)}`);
+    }));
+    canvas
+        .command("pull")
+        .description("Save a canvas as tldraw JSON")
+        .argument("<canvas>", "canvas id (cnv_…) or URL")
+        .option("-o, --out <path>", "file to write (default: <id>.json)")
+        .action(action(async (ctx, ref, opts) => {
+        const { id } = parseRef(ref, "canvas");
+        const row = await ctx.api.get(`/canvases/${id}`);
+        const path = opts.out ?? `${id}.json`;
+        await writeFile(path, `${JSON.stringify(row.document ?? {}, null, 2)}\n`);
+        emit({ ...item(ctx, "canvas", row), file: path }, (d) => `Saved “${d.title}” to ${d.file}`);
+    }));
+    canvas
+        .command("push")
+        .description("Replace a canvas with tldraw JSON (from `canvas pull`)")
+        .argument("<file>", 'tldraw snapshot JSON ("-" for stdin)')
+        .requiredOption("--id <canvas>", "canvas to update")
+        .action(action(async (ctx, file, opts) => {
+        const { id } = parseRef(opts.id, "canvas");
+        const document = parseSnapshot((await readContent({ file })) ?? "");
+        const row = await ctx.api.patch(`/canvases/${id}`, {
+            document,
+        });
+        emit(item(ctx, "canvas", row), (i) => `Updated ${describeItem(i)}`);
+    }));
+}

package/dist/commands/items.js

@@ -0,0 +1,225 @@
+import { resolveNotebook } from "../core/context.js";
+import { usage } from "../core/errors.js";
+import { openBrowser } from "../core/login.js";
+import { emit, table } from "../core/output.js";
+import { appUrl, KIND_NAME, parseRef } from "../core/refs.js";
+import { describeItem, item, setPublished, } from "../core/resources.js";
+import { action } from "../core/run.js";
+const LIST_PATH = {
+    page: "pages",
+    canvas: "canvases",
+    project: "projects",
+    notebook: "notebooks",
+};
+const KIND_ALIASES = {
+    note: "page",
+    notes: "page",
+    page: "page",
+    canvas: "canvas",
+    canvases: "canvas",
+    project: "project",
+    projects: "project",
+    notebook: "notebook",
+    notebooks: "notebook",
+};
+async function listAll(ctx, kinds) {
+    const ws = await ctx.workspaceId();
+    const lists = await Promise.all(kinds.map(async (kind) => (await ctx.api.get(`/workspaces/${ws}/${LIST_PATH[kind]}`)).map((r) => ({
+        ...item(ctx, kind, r),
+        published: Boolean(r.publishedAt),
+    }))));
+    return lists
+        .flat()
+        .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
+}
+const listTable = (items) => table(items.map((i) => ({
+    kind: i.kind,
+    id: i.id,
+    title: i.title.length > 48 ? `${i.title.slice(0, 47)}…` : i.title,
+    updated: (i.updatedAt ?? "").slice(0, 10),
+    public: i.published ? "yes" : "",
+})), ["kind", "id", "title", "updated", "public"]);
+const ROUTE = {
+    page: "pages",
+    canvas: "canvases",
+    project: "projects",
+    notebook: "notebooks",
+};
+export function registerItems(program) {
+    program
+        .command("list")
+        .alias("ls")
+        .description("List notes, canvases, projects and notebooks (newest first)")
+        .option("-k, --kind <kind>", "only this kind: note | canvas | project | notebook")
+        .option("-n, --notebook <notebook>", "only what's inside this notebook (id or exact name)")
+        .action(action(async (ctx, opts) => {
+        const only = opts.kind
+            ? KIND_ALIASES[opts.kind.toLowerCase()]
+            : undefined;
+        if (opts.kind && !only)
+            throw usage(`Unknown kind "${opts.kind}".`, "Use note, canvas, project or notebook.");
+        if (opts.notebook) {
+            const nb = await resolveNotebook(ctx, opts.notebook);
+            const c = await ctx.api.get(`/notebooks/${nb.id}`);
+            const items = [
+                ...c.notes.map((r) => ({
+                    ...item(ctx, "page", r),
+                    published: Boolean(r.publishedAt),
+                })),
+                ...c.canvases.map((r) => ({
+                    ...item(ctx, "canvas", r),
+                    published: Boolean(r.publishedAt),
+                })),
+                ...c.projects.map((r) => ({
+                    ...item(ctx, "project", r),
+                    published: Boolean(r.publishedAt),
+                })),
+            ].filter((i) => !only || i.kind === KIND_NAME[only]);
+            return emit(items, listTable);
+        }
+        emit(await listAll(ctx, only ? [only] : ["page", "canvas", "project", "notebook"]), listTable);
+    }));
+    program
+        .command("search")
+        .description("Find notes, canvases, projects and notebooks by title")
+        .argument("<query...>", "words to look for in titles")
+        .action(action(async (ctx, words) => {
+        const terms = words
+            .join(" ")
+            .toLowerCase()
+            .split(/\s+/)
+            .filter(Boolean);
+        const all = await listAll(ctx, [
+            "page",
+            "canvas",
+            "project",
+            "notebook",
+        ]);
+        emit(all.filter((i) => terms.every((t) => i.title.toLowerCase().includes(t))), listTable);
+    }));
+    program
+        .command("open")
+        .description("Print the app link for an item (and open it when run in a terminal)")
+        .argument("<id>", "any Octonote id or URL")
+        .action(action(async (ctx, ref) => {
+        const { kind, id } = parseRef(ref);
+        const url = appUrl(ctx.config.webUrl, kind, id);
+        if (process.stdout.isTTY)
+            openBrowser(url);
+        emit({ kind: KIND_NAME[kind], id, url }, (d) => d.url);
+    }));
+    program
+        .command("move")
+        .description("Move a note, canvas or project into a notebook (or out with --out)")
+        .argument("<id>", "note, canvas or project id")
+        .option("-n, --notebook <notebook>", "target notebook (id or exact name)")
+        .option("--out", "take it out of its notebook")
+        .action(action(async (ctx, ref, opts) => {
+        const { kind, id } = parseRef(ref);
+        if (kind === "notebook")
+            throw usage("Notebooks can't go inside notebooks.");
+        if (!opts.notebook && !opts.out)
+            throw usage("Where to?", "Pass --notebook <name|id> or --out.");
+        const notebookId = opts.out
+            ? null
+            : (await resolveNotebook(ctx, opts.notebook)).id;
+        const row = await ctx.api.post(`/${ROUTE[kind]}/${id}/move`, {
+            notebookId,
+        });
+        emit(item(ctx, kind, row), (i) => `Moved ${describeItem(i)}`);
+    }));
+    program
+        .command("delete")
+        .alias("rm")
+        .description("Delete a note, canvas, project or notebook (a notebook's contents move to the top level)")
+        .argument("<id>", "any Octonote id")
+        .option("-y, --yes", "required: confirms the delete (agents: only when the user asked)")
+        .action(action(async (ctx, ref, opts) => {
+        const { kind, id } = parseRef(ref);
+        if (!opts.yes)
+            throw usage(`Deleting ${KIND_NAME[kind]} ${id} needs --yes.`, "Deleted items can't be restored from the CLI.");
+        await ctx.api.delete(`/${ROUTE[kind]}/${id}`);
+        emit({ kind: KIND_NAME[kind], id, deleted: true }, () => `Deleted ${KIND_NAME[kind]} ${id}`);
+    }));
+    for (const [name, published] of [
+        ["publish", true],
+        ["unpublish", false],
+    ]) {
+        program
+            .command(name)
+            .description(published
+            ? "Publish to the web; prints the public URL"
+            : "Stop publishing to the web")
+            .argument("<id>", "any Octonote id")
+            .action(action(async (ctx, ref) => {
+            const { kind, id } = parseRef(ref);
+            const state = await setPublished(ctx, kind, id, published);
+            emit({
+                kind: KIND_NAME[kind],
+                id,
+                published: state.published,
+                publicUrl: state.publicUrl,
+            }, (d) => d.published
+                ? `Published: ${d.publicUrl}`
+                : `Unpublished ${d.kind} ${d.id}`);
+        }));
+    }
+    program
+        .command("share")
+        .description("Share with a person by email, or set who can open the link")
+        .argument("<id>", "any Octonote id")
+        .option("-e, --email <email>", "invite this person (they get an email; non-users join on sign-up)")
+        .option("-r, --role <role>", "viewer | editor", "viewer")
+        .option("--link <access>", "anyone with the link: off | view | edit")
+        .action(action(async (ctx, ref, opts) => {
+        const { kind, id } = parseRef(ref);
+        const role = opts.role === "editor"
+            ? "editor"
+            : opts.role === "viewer"
+                ? "viewer"
+                : null;
+        if (!role)
+            throw usage(`Unknown role "${opts.role}".`, "Use viewer or editor.");
+        if (!opts.email && !opts.link)
+            throw usage("Share with whom?", "Pass --email <address> and/or --link off|view|edit.");
+        const result = {
+            kind: KIND_NAME[kind],
+            id,
+            url: appUrl(ctx.config.webUrl, kind, id),
+        };
+        if (opts.link) {
+            const map = {
+                off: { linkAccess: "restricted", linkRole: "viewer" },
+                view: { linkAccess: "anyone_with_link", linkRole: "viewer" },
+                edit: { linkAccess: "anyone_with_link", linkRole: "editor" },
+            };
+            const body = map[opts.link];
+            if (!body)
+                throw usage(`Unknown --link "${opts.link}".`, "Use off, view or edit.");
+            await ctx.api.put(`/${kind}/${id}/general-access`, body);
+            result.link = opts.link;
+        }
+        if (opts.email) {
+            const share = await ctx.api.post("/shares", {
+                resourceKind: kind,
+                resourceId: id,
+                email: opts.email,
+                role,
+            });
+            result.invited = {
+                email: opts.email.toLowerCase(),
+                role,
+                emailSent: share.emailSent ?? false,
+            };
+        }
+        emit(result, (d) => [
+            d.link ? `Link access: ${d.link}` : "",
+            d.invited
+                ? `Invited ${d.invited.email} as ${role}`
+                : "",
+            `${d.url}`,
+        ]
+            .filter(Boolean)
+            .join("\n"));
+    }));
+}