@simplepush/cli 0.2.0 → 0.3.0

package/README.md

@@ -22,6 +22,7 @@ sp cancel    Withdraw a pending task, subtask, or task group you sent.
 sp notify    Send a fire-and-forget notification.
 sp collect   Collect replies, inputs, or submissions as bounded NDJSON.
 sp download  Download one file a collect line referenced, by its ids.
+sp get       Read what came back: task listings, one task with its subtasks, a task group, submissions.
 sp events    Stream or replay the raw event feed.
 sp auth      Log in to an organization (login / logout / status).
 sp org       Administer an organization: members, invites, topics, API key, encryption.
@@ -192,3 +193,18 @@ Bun can compile the CLI into a single-file native binary:
 bun run build:binary
 ./bin/simplepush --help
 ```
+
+### Query what came back
+
+The read commands mirror the MCP query tools, so an agent can ask questions like "every task that expired unanswered this week, grouped by assignee":
+
+```bash
+sp get tasks --status expired --since 7d --format json  # one JSON object per line
+sp get tasks --status pending --member anna --all       # follow cursors to the end
+sp get tsk_…                                            # the chain: root + subtasks, decrypted where keys are held
+sp get grptsk_…                                         # per-recipient status of a group send
+sp get submissions --since 24h --member anna
+sp events --since 7d --member anna                      # events replay, narrowed client-side
+```
+
+A page that was cut off ends with `{"type":"more","cursor":"…"}` (`json`) or an info line (`pretty`); pass the cursor back with `--cursor`, or `--all` to page automatically. `--since`/`--until` take ISO-8601 instants or relative windows (`7d`, `12h`). For personal accounts the HTTP query surface (`sp get`) is a subscription feature — `sp events`, `sp collect` and `sp download` stay free.

package/dist/main.mjs

@@ -9,7 +9,7 @@ import { wordlist } from "@scure/bip39/wordlists/english.js";
 import { homedir, tmpdir } from "node:os";
 import { createServer } from "node:http";
 import { spawn } from "node:child_process";
-import { Client, Keyring, OrgClient, TypeFilter, cancelSubtask, cancelTask, cancelTaskGroup, decryptBytes, deriveKey, encrypt, fetchUserInfo, isSubtaskGroupResponse, tryDecryptEventData } from "@simplepush/sdk";
+import { Client, Keyring, OrgClient, TypeFilter, cancelSubtask, cancelTask, cancelTaskGroup, decryptBytes, decryptSubmission, decryptTaskPayload, decryptTaskSummary, deriveKey, encrypt, fetchUserInfo, isSubtaskGroupResponse, tryDecryptEventData } from "@simplepush/sdk";
 import { mkdir, stat, writeFile } from "node:fs/promises";
 import { connect, createConnection } from "node:net";
 import path, { basename, extname, join } from "node:path";
@@ -546,7 +546,7 @@ var VaultAccess = class extends Effect.Service()("cli/VaultAccess", {
 //#region src/global-options.ts
 const DEFAULT_BASE_URL = "https://api.simplepu.sh";
 const toHelp = (e) => HelpDoc.p(e instanceof Error ? e.message : String(e));
-const topicOption = Options.text("topic").pipe(Options.withAlias("t"), Options.withDescription("Topic to send to (`task`) or filter on (`events`, repeatable). Omit on `task` for a self-send to your own devices."), Options.repeated);
+const topicOption$1 = Options.text("topic").pipe(Options.withAlias("t"), Options.withDescription("Topic to send to (`task`) or filter on (`events`, repeatable). Omit on `task` for a self-send to your own devices."), Options.repeated);
 const apiTokenOption = Options.text("api-token").pipe(Options.withDescription("API token. Required for `get`; `collect`, `events`, and `subtask` fall back to the logged-in org session when omitted. Defaults to $SP_API_TOKEN."), Options.withFallbackConfig(Config.string("SP_API_TOKEN")), Options.optional);
 /** Personal-credential commands need the token; fail typed when absent. */
 const requireApiToken = (token) => Option.match(token, {
@@ -1164,7 +1164,7 @@ function formatSent(groupId, createdAt, members) {
 		type: "sent",
 		groupId: groupId ?? null,
 		createdAt: createdAt ?? null,
-		members: members.map((m) => ({
+		instances: members.map((m) => ({
 			...m.kind === "notification" ? { notificationId: m.id } : { taskId: m.id },
 			...m.subtaskId !== void 0 ? { subtaskId: m.subtaskId } : {},
 			recipient: m.recipient
@@ -1303,14 +1303,14 @@ function fileViewsOf(item) {
 	]).filter(isFileView);
 }
 /** The terminal line: reason the stream stopped, per-type counts, and (for
-* group modes) per-member status. Always the last line on a clean run. */
+* group modes) per-instance status. Always the last line on a clean run. */
 function formatEnd(reason, counts, members, errorMsg) {
 	const obj = {
 		type: "end",
 		reason,
 		counts
 	};
-	if (members) obj.members = members;
+	if (members) obj.instances = members;
 	if (errorMsg !== void 0) obj.error = errorMsg;
 	return line(obj);
 }
@@ -1463,7 +1463,7 @@ const SentLine = Schema.Struct({
 	type: Schema.Literal("sent"),
 	groupId: Schema.optional(Schema.NullOr(Schema.String)),
 	createdAt: Schema.optional(Schema.NullOr(Schema.String)),
-	members: Schema.optional(Schema.Array(Schema.Struct({
+	instances: Schema.optional(Schema.Array(Schema.Struct({
 		taskId: Schema.optional(Schema.String),
 		notificationId: Schema.optional(Schema.String),
 		subtaskId: Schema.optional(Schema.String),
@@ -1525,9 +1525,9 @@ const loadOrgMasterKeys = Effect.gen(function* () {
 });
 const collectCommand = Command.make("collect", {
 	group: Options.text("group").pipe(Options.withDescription("Group id (grptsk_…) to collect over. Usually supplied via the piped `sent` line instead."), Options.optional),
-	instance: Options.text("instance").pipe(Options.withDescription("Member instance id to collect: a task (tsk_…), a notification (ntf_…), or a subtask-scoped pair (tsk_…/sub_…). Repeatable. Augments/overrides the piped `sent` line's members."), Options.repeated),
+	instance: Options.text("instance").pipe(Options.withDescription("Instance id to collect: a task (tsk_…), a notification (ntf_…), or a subtask-scoped pair (tsk_…/sub_…). Repeatable. Augments/overrides the piped `sent` line's instances."), Options.repeated),
 	replies: Options.boolean("replies").pipe(Options.withDescription("Collect only replies. Default (no mode flag) is the full activity stream: inputs, replies, and completions.")),
-	inputs: Options.boolean("inputs").pipe(Options.withDescription("Collect only input events (waits for every member to complete by default).")),
+	inputs: Options.boolean("inputs").pipe(Options.withDescription("Collect only input events (waits for every instance to complete by default).")),
 	submissions: Options.boolean("submissions").pipe(Options.withDescription("Collect submissions (your inbox) instead of a group's events.")),
 	since: mappedText("since", resolveSince).pipe(Options.withDescription("Resume point (`24h`, `7d`, or ISO 8601). Backfills group events or submissions from that point; defaults to the send's createdAt from the piped `sent` line. Implies --direct (the broker can't serve a deep backfill)."), Options.optional),
 	until: Options.text("until").pipe(Options.withDescription("Stop condition. Repeatable: complete | idle:<dur> | count:<n> | timeout:<dur> | forever (never stop; Ctrl-C to end). Default: complete for group collects; --replies / --submissions watch forever."), Options.repeated),
@@ -1600,7 +1600,7 @@ const collectCommand = Command.make("collect", {
 				});
 			}
 		};
-		for (const m of sent?.members ?? []) addMember(m.taskId ?? m.notificationId, m.recipient ? {
+		for (const m of sent?.instances ?? []) addMember(m.taskId ?? m.notificationId, m.recipient ? {
 			publicId: m.recipient.publicId,
 			name: m.recipient.name ?? null
 		} : null, m.subtaskId);
@@ -1609,11 +1609,11 @@ const collectCommand = Command.make("collect", {
 			if (id.startsWith("sub_")) return yield* Effect.fail(new UserError({ message: `a subtask cannot be collected by its id alone (events route under the parent task) — pass --instance <parent tsk_…>/${id}` }));
 			addMember(id, null, subtaskId);
 		}
-		if (members.length === 0) return yield* Effect.fail(new UserError({ message: "no members to collect: pipe a send's `sent` line (`sp task --format json | sp collect`) or pass --instance <tsk_…|ntf_…|tsk_…/sub_…> (repeatable)" }));
+		if (members.length === 0) return yield* Effect.fail(new UserError({ message: "no instances to collect: pipe a send's `sent` line (`sp task --format json | sp collect`) or pass --instance <tsk_…|ntf_…|tsk_…/sub_…> (repeatable)" }));
 		const notifRoster = members[0].kind === "notification";
-		if (members.some((m) => m.kind === "notification" !== notifRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix task (tsk_…) and notification (ntf_…) members in one collect — run one per kind" }));
+		if (members.some((m) => m.kind === "notification" !== notifRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix task (tsk_…) and notification (ntf_…) instances in one collect — run one per kind" }));
 		const subRoster = members[0].subtaskId !== void 0;
-		if (members.some((m) => m.subtaskId !== void 0 !== subRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix subtask-scoped members (a piped `sp subtask --format json` line or --instance tsk_…/sub_…) with plain task/notification members in one collect" }));
+		if (members.some((m) => m.subtaskId !== void 0 !== subRoster)) return yield* Effect.fail(new UserError({ message: "cannot mix subtask-scoped instances (a piped `sp subtask --format json` line or --instance tsk_…/sub_…) with plain task/notification instances in one collect" }));
 		const streamOpts = {
 			replay: true,
 			...until.idleMs !== void 0 ? { idleMs: until.idleMs } : {}
@@ -1675,7 +1675,7 @@ const collectCommand = Command.make("collect", {
 			});
 		}
 		if (args.format === "json") yield* out.print(formatSent(groupId, createdAt, members));
-		else yield* out.info(`collecting ${mode} over ${members.length} member(s)${groupId ? ` of ${groupId}` : ""}`);
+		else yield* out.info(`collecting ${mode} over ${members.length} instance(s)${groupId ? ` of ${groupId}` : ""}`);
 		yield* collectGroup(watchGroupId, source, members, args.format, until, saveDir);
 	}));
 }));
@@ -2099,11 +2099,12 @@ function extractRaw(v) {
 //#endregion
 //#region src/commands/events.ts
 const eventTypeOption = Options.text("type").pipe(Options.withDescription("Filter by event type. Repeatable."), Options.repeated);
-const sinceOption = mappedText("since", resolveSince).pipe(Options.withDescription("Replay from this point. Accepts `24h`, `7d`, or an ISO 8601 timestamp."), Options.optional);
-const untilOption = mappedText("until", resolveUntil).pipe(Options.withDescription("Stop at this timestamp. Forces a finite range, so `--follow` is ignored."), Options.optional);
-const limitOption = Options.integer("limit").pipe(Options.withDescription("Maximum number of events to print, then exit."), Options.optional);
+const sinceOption$1 = mappedText("since", resolveSince).pipe(Options.withDescription("Replay from this point. Accepts `24h`, `7d`, or an ISO 8601 timestamp."), Options.optional);
+const untilOption$1 = mappedText("until", resolveUntil).pipe(Options.withDescription("Stop at this timestamp. Forces a finite range, so `--follow` is ignored."), Options.optional);
+const limitOption$1 = Options.integer("limit").pipe(Options.withDescription("Maximum number of events to print, then exit."), Options.optional);
 const followOption = Options.boolean("follow").pipe(Options.withAlias("f"), Options.withDescription("After history is drained, keep streaming live instead of exiting. Only meaningful with `--since`."));
-const formatOption$3 = Options.choice("format", [
+const memberOption$3 = Options.text("member").pipe(Options.optional, Options.withDescription("Only events by this person: a usr_ id, or the actor's name."));
+const formatOption$4 = Options.choice("format", [
 	"json",
 	"pretty",
 	"raw"
@@ -2112,13 +2113,14 @@ const directOption = Options.boolean("direct").pipe(Options.withDescription("Ope
 const QUIET_EXIT_MS = 2e3;
 const eventsCommand = Command.make("events", {
 	type: eventTypeOption,
-	since: sinceOption,
-	until: untilOption,
-	limit: limitOption,
+	member: memberOption$3,
+	since: sinceOption$1,
+	until: untilOption$1,
+	limit: limitOption$1,
 	follow: followOption,
-	format: formatOption$3,
+	format: formatOption$4,
 	direct: directOption,
-	topic: topicOption,
+	topic: topicOption$1,
 	"api-token": apiTokenOption,
 	password: passwordOption,
 	"base-url": baseUrlOption,
@@ -2132,6 +2134,8 @@ const eventsCommand = Command.make("events", {
 	const untilDate = Option.getOrUndefined(args.until);
 	const limit = Option.getOrUndefined(args.limit);
 	const filter = new TypeFilter(args.type);
+	const member = Option.getOrUndefined(args.member);
+	const memberMatches = (ev) => member === void 0 || ev.actor?.publicId === member || ev.actor?.name === member;
 	yield* Effect.forEach(filter.unknown, (u) => out.warn(`ignoring unknown --type \`${u}\``));
 	const webSocketFactory = args.direct || sinceIso !== void 0 ? Option.none() : yield* sharedWebSocketFactory({
 		credential: cred.kind === "personal" ? {
@@ -2194,7 +2198,7 @@ const eventsCommand = Command.make("events", {
 		yield* sdkStream("events stream", (signal) => client.events({
 			...sinceIso !== void 0 ? { since: sinceIso } : {},
 			signal: AbortSignal.any([signal, endController.signal])
-		})).pipe(Stream.tap(() => Ref.set(lastActivity, Date.now())), Stream.interruptWhen(Deferred.await(halt)), untilDate !== void 0 ? Stream.takeUntilEffect((ev) => untilReached(ev) ? note("--until reached, exiting").pipe(Effect.zipRight(Deferred.succeed(halt, void 0)), Effect.as(true)) : Effect.succeed(false)) : (s) => s, Stream.filter((ev) => !untilReached(ev) && filter.matches(ev)), Stream.mapEffect((ev) => Effect.gen(function* () {
+		})).pipe(Stream.tap(() => Ref.set(lastActivity, Date.now())), Stream.interruptWhen(Deferred.await(halt)), untilDate !== void 0 ? Stream.takeUntilEffect((ev) => untilReached(ev) ? note("--until reached, exiting").pipe(Effect.zipRight(Deferred.succeed(halt, void 0)), Effect.as(true)) : Effect.succeed(false)) : (s) => s, Stream.filter((ev) => !untilReached(ev) && filter.matches(ev) && memberMatches(ev)), Stream.mapEffect((ev) => Effect.gen(function* () {
 			const decrypted = keyring ? yield* sdkCall("decrypt event", () => tryDecryptEventData(ev, keyring)) : void 0;
 			yield* out.print(formatEvent(ev, args.format, decrypted));
 			const n = yield* Ref.updateAndGet(printed, (x) => x + 1);
@@ -2212,6 +2216,313 @@ const eventsCommand = Command.make("events", {
 	}));
 }));
 //#endregion
+//#region src/commands/query-support.ts
+/** Options every read command shares: credential, decryption keys, paging, output. */
+const credentialOptions = {
+	"api-token": apiTokenOption,
+	password: passwordOption,
+	"base-url": baseUrlOption,
+	quiet: quietOption
+};
+const formatOption$3 = Options.choice("format", ["json", "pretty"]).pipe(Options.withDefault("json"), Options.withDescription("json = one JSON object per line (agents, jq); pretty = human-readable lines."));
+const sinceOption = mappedText("since", resolveSince).pipe(Options.optional, Options.withDescription("Only items created at or after this instant: ISO-8601, or a relative window like 7d, 12h, 30m."));
+const untilOption = mappedText("until", (raw) => resolveUntil(raw).toISOString()).pipe(Options.optional, Options.withDescription("Only items created at or before this instant (same forms as --since)."));
+const memberOption$2 = Options.text("member").pipe(Options.optional, Options.withDescription("Only items involving this person: a usr_ id, or a member name on an org."));
+const limitOption = Options.integer("limit").pipe(Options.optional, Options.withDescription("Page size (server default 50). With --all this is the page size, not a cap."));
+const cursorOption = Options.text("cursor").pipe(Options.optional, Options.withDescription("Continue a previous page: pass the cursor it reported."));
+const allOption = Options.boolean("all").pipe(Options.withDescription("Follow cursors until the last page instead of printing one page and a cursor."));
+const STATUSES = [
+	"pending",
+	"completed",
+	"canceled",
+	"declined",
+	"expired"
+];
+/** `--status` accepts repeats and comma lists: `--status expired --status declined` or `--status expired,declined`. */
+const statusOption = Options.text("status").pipe(Options.repeated, Options.mapTryCatch((values) => {
+	const flat = values.flatMap((v) => v.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
+	const bad = flat.filter((s) => !STATUSES.includes(s));
+	if (bad.length > 0) throw new Error(`unknown status ${bad.join(", ")} — use ${STATUSES.join(", ")}`);
+	return flat;
+}, (e) => HelpDoc.p(e instanceof Error ? e.message : String(e))), Options.withDescription("Only tasks in these states (repeatable or comma-separated)."));
+/** Resolves the credential (personal API-Token or the saved org session),
+* builds the matching client and — when keys are available — a keyring, and
+* runs `body` inside the client's scope. Mirrors what `sp events` does. */
+const withQueryClient = (args, body) => Effect.gen(function* () {
+	const out = yield* CliOutput;
+	yield* out.setQuiet(args.quiet);
+	const cred = yield* resolveCredential(args["api-token"], args["base-url"]);
+	const orgKeys = cred.kind === "org" ? yield* loadOrgMasterKeys : void 0;
+	return yield* Effect.scoped(Effect.gen(function* () {
+		const client = cred.kind === "personal" ? yield* acquireClient({
+			baseUrl: cred.baseUrl,
+			apiToken: cred.apiToken,
+			passwords: args.password
+		}) : yield* acquireOrgClient({
+			baseUrl: cred.baseUrl,
+			bearerToken: cred.bearer,
+			...orgKeys !== void 0 ? { orgMasterKeys: orgKeys } : {}
+		});
+		return yield* body({
+			client,
+			keyring: cred.kind === "org" ? orgKeys !== void 0 ? yield* sdkCall("keyring", () => client.keyring()) : void 0 : args.password.length > 0 ? yield* sdkCall("keyring", () => client.keyring({ includePasswordSalt: true })) : void 0,
+			org: cred.kind === "org",
+			out
+		});
+	}));
+});
+/** Decrypts what the keyring can and counts what it cannot, so a command can
+* report "N values left as ciphertext" once instead of per row. Each method
+* maps one wire shape onto its SDK field-schema decryptor. */
+var Decryptor = class {
+	undecryptable = 0;
+	constructor(keyring) {
+		this.keyring = keyring;
+	}
+	run(value, go) {
+		if (this.keyring === void 0) return Effect.succeed(value);
+		const keyring = this.keyring;
+		return Effect.promise(() => go(keyring)).pipe(Effect.map((r) => {
+			this.undecryptable += r.undecryptable;
+			return r.value;
+		}));
+	}
+	/** A task or subtask payload (chain reads). */
+	payload(value) {
+		return this.run(value, (kr) => decryptTaskPayload(value, kr));
+	}
+	/** A task index / roster row. */
+	summary(value) {
+		return this.run(value, (kr) => decryptTaskSummary(value, kr));
+	}
+	/** A submission under its feed entry's marker. */
+	submission(value, marker) {
+		return this.run(value, (kr) => decryptSubmission(value, kr, marker));
+	}
+	report(out) {
+		return this.undecryptable > 0 ? out.warn(`${this.undecryptable} value(s) are encrypted under a key this CLI does not hold and were left as ciphertext`) : Effect.void;
+	}
+};
+/** Runs `page` for the first cursor, then keeps following cursors when `all`
+* is set; otherwise reports the cursor of the next page so the caller can
+* continue by hand. */
+const forEachPage = (ctx, format, all, first, page, handle) => Effect.gen(function* () {
+	let cursor = first;
+	for (;;) {
+		const p = yield* page(cursor);
+		yield* handle(p);
+		if (p.nextCursor === void 0) return;
+		if (!all) {
+			yield* format === "json" ? ctx.out.print(JSON.stringify({
+				type: "more",
+				cursor: p.nextCursor
+			})) : ctx.out.info(`more available — continue with --cursor ${p.nextCursor} (or pass --all)`);
+			return;
+		}
+		cursor = p.nextCursor;
+	}
+});
+function recipientLabels(t) {
+	return t.recipients.map((r) => r.name ?? r.publicId);
+}
+/** One line per task: id, state, when, title, who, subtask counts, group. */
+function formatTaskSummary(t) {
+	const subs = Object.entries(t.subtasks).map(([k, v]) => `${k} ${v}`).join(", ");
+	return [
+		`${t.taskId}  [${t.status}]  ${t.createdAt}`,
+		t.title !== void 0 ? `  ${t.title}` : void 0,
+		`  to: ${recipientLabels(t).join(", ") || "-"}`,
+		t.inputs.length > 0 ? `  inputs: ${t.inputs.join(", ")}` : void 0,
+		t.reply !== void 0 ? `  reply: ${t.reply}` : void 0,
+		subs ? `  subtasks: ${subs}` : void 0,
+		t.expiresAt !== void 0 ? `  expires: ${t.expiresAt}` : void 0,
+		t.groupId !== void 0 ? `  group: ${t.groupId}` : void 0
+	].filter((l) => l !== void 0).join("\n");
+}
+//#endregion
+//#region src/commands/get.ts
+const topicOption = Options.text("topic").pipe(Options.optional, Options.withDescription("Only tasks sent to this topic: its value (name), or its id."));
+const groupOption = Options.text("group").pipe(Options.optional, Options.withDescription("Only the instances of this grptsk_ group."));
+/** Flags that only make sense on the paged listings. Id reads reject them by
+* name instead of silently ignoring them. */
+function rejectListFlags(args, target, allowStatus) {
+	const set = [
+		...!allowStatus && args.status.length > 0 ? ["--status"] : [],
+		...Option.isSome(args.since) ? ["--since"] : [],
+		...Option.isSome(args.until) ? ["--until"] : [],
+		...Option.isSome(args.topic) ? ["--topic"] : [],
+		...Option.isSome(args.member) ? ["--member"] : [],
+		...Option.isSome(args.group) ? ["--group"] : [],
+		...Option.isSome(args.limit) ? ["--limit"] : [],
+		...Option.isSome(args.cursor) ? ["--cursor"] : [],
+		...args.all ? ["--all"] : []
+	];
+	return set.length === 0 ? Effect.void : Effect.fail(new UserError({ message: `${set.join(", ")} does not apply when reading ${target}` }));
+}
+function getChain(args, ctx) {
+	return Effect.gen(function* () {
+		yield* rejectListFlags(args, "one task", false);
+		const chain = yield* sdkCall("read task chain", () => ctx.client.getTaskChain(args.what));
+		const dec = new Decryptor(ctx.keyring);
+		const task = yield* dec.payload(chain.task);
+		const subtasks = [];
+		for (const s of chain.subtasks) subtasks.push({
+			subtask: yield* dec.payload(s.subtask),
+			createdAt: s.createdAt
+		});
+		const view = {
+			task,
+			createdAt: chain.createdAt,
+			subtasks
+		};
+		if (args.format === "json") yield* ctx.out.print(JSON.stringify(view));
+		else {
+			yield* ctx.out.print(`${task.taskId}  [${task.status}]  ${chain.createdAt}`);
+			yield* ctx.out.print(JSON.stringify(task, null, 2));
+			for (const s of subtasks) {
+				yield* ctx.out.print(`\n${s.subtask.subtaskId}  [${s.subtask.status}]  ${s.createdAt}`);
+				yield* ctx.out.print(JSON.stringify(s.subtask, null, 2));
+			}
+		}
+		yield* dec.report(ctx.out);
+	});
+}
+function getRoster(args, ctx) {
+	return Effect.gen(function* () {
+		yield* rejectListFlags(args, "a task group roster", true);
+		const roster = yield* sdkCall("read task group", () => ctx.client.getTaskGroup(args.what, args.status.length > 0 ? { status: args.status } : {}));
+		const dec = new Decryptor(ctx.keyring);
+		const counts = {};
+		for (const t of roster.tasks) counts[t.status] = (counts[t.status] ?? 0) + 1;
+		if (args.format === "json") {
+			yield* ctx.out.print(JSON.stringify({
+				type: "group",
+				groupId: roster.groupId,
+				counts
+			}));
+			for (const t of roster.tasks) yield* ctx.out.print(JSON.stringify(yield* dec.summary(t)));
+		} else {
+			const summary = Object.entries(counts).map(([k, v]) => `${k} ${v}`).join(", ") || "no instances";
+			yield* ctx.out.print(`${roster.groupId}  ${summary}`);
+			for (const t of roster.tasks) yield* ctx.out.print(formatTaskSummary(yield* dec.summary(t)));
+		}
+		yield* dec.report(ctx.out);
+	});
+}
+function getTasks(args, ctx) {
+	return Effect.gen(function* () {
+		const dec = new Decryptor(ctx.keyring);
+		const opts = {
+			...args.status.length > 0 ? { status: args.status } : {},
+			...Option.match(args.since, {
+				onNone: () => ({}),
+				onSome: (since) => ({ since })
+			}),
+			...Option.match(args.until, {
+				onNone: () => ({}),
+				onSome: (until) => ({ until })
+			}),
+			...Option.match(args.topic, {
+				onNone: () => ({}),
+				onSome: (topic) => ({ topic })
+			}),
+			...Option.match(args.member, {
+				onNone: () => ({}),
+				onSome: (member) => ({ member })
+			}),
+			...Option.match(args.group, {
+				onNone: () => ({}),
+				onSome: (group) => ({ group })
+			}),
+			...Option.match(args.limit, {
+				onNone: () => ({}),
+				onSome: (limit) => ({ limit })
+			})
+		};
+		yield* forEachPage(ctx, args.format, args.all, Option.getOrUndefined(args.cursor), (cursor) => sdkCall("list tasks", () => ctx.client.listTasks({
+			...opts,
+			...cursor !== void 0 ? { cursor } : {}
+		})), (page) => Effect.forEach(page.tasks, (t) => Effect.gen(function* () {
+			const row = yield* dec.summary(t);
+			yield* ctx.out.print(args.format === "json" ? JSON.stringify(row) : formatTaskSummary(row));
+		}), { discard: true }));
+		yield* dec.report(ctx.out);
+	});
+}
+function getSubmissions(args, ctx) {
+	return Effect.gen(function* () {
+		const wrong = [
+			...args.status.length > 0 ? ["--status"] : [],
+			...Option.isSome(args.topic) ? ["--topic"] : [],
+			...Option.isSome(args.group) ? ["--group"] : []
+		];
+		if (wrong.length > 0) return yield* Effect.fail(new UserError({ message: `${wrong.join(", ")} does not apply to submissions` }));
+		const dec = new Decryptor(ctx.keyring);
+		const opts = {
+			...Option.match(args.since, {
+				onNone: () => ({}),
+				onSome: (since) => ({ since })
+			}),
+			...Option.match(args.until, {
+				onNone: () => ({}),
+				onSome: (until) => ({ until })
+			}),
+			...Option.match(args.member, {
+				onNone: () => ({}),
+				onSome: (member) => ({ member })
+			}),
+			...Option.match(args.limit, {
+				onNone: () => ({}),
+				onSome: (limit) => ({ limit })
+			})
+		};
+		yield* forEachPage(ctx, args.format, args.all, Option.getOrUndefined(args.cursor), (cursor) => sdkCall("list submissions", () => ctx.client.listSubmissions({
+			...opts,
+			...cursor !== void 0 ? { cursor } : {}
+		})), (page) => Effect.forEach(page.submissions, (entry) => Effect.gen(function* () {
+			const submission = yield* dec.submission(entry.submission, entry.encryption);
+			const by = entry.actor?.name ?? entry.actor?.publicId;
+			if (args.format === "json") yield* ctx.out.print(JSON.stringify({
+				...submission,
+				...entry.actor !== void 0 ? { actor: entry.actor } : {}
+			}));
+			else {
+				const body = submission.body;
+				const parts = [
+					body?.value !== void 0 ? body.value : void 0,
+					submission.photo !== void 0 ? "[photo]" : void 0,
+					submission.file !== void 0 ? "[file]" : void 0,
+					submission.audio !== void 0 ? "[audio]" : void 0,
+					submission.location !== void 0 ? "[location]" : void 0
+				].filter((p) => p !== void 0);
+				yield* ctx.out.print(`${submission.id}  ${submission.createdAt}  ${by ?? "-"}: ${parts.join(" ") || "(empty)"}`);
+			}
+		}), { discard: true }));
+		yield* dec.report(ctx.out);
+	});
+}
+const getCommand = Command.make("get", {
+	what: Args.text({ name: "what" }).pipe(Args.withDescription("What to read: tasks, submissions, a tsk_ id, or a grptsk_ id.")),
+	status: statusOption,
+	since: sinceOption,
+	until: untilOption,
+	topic: topicOption,
+	member: memberOption$2,
+	group: groupOption,
+	limit: limitOption,
+	cursor: cursorOption,
+	all: allOption,
+	format: formatOption$3,
+	...credentialOptions
+}, (args) => withQueryClient(args, (ctx) => {
+	if (args.what === "tasks") return getTasks(args, ctx);
+	if (args.what === "submissions") return getSubmissions(args, ctx);
+	if (args.what.startsWith("tsk_")) return getChain(args, ctx);
+	if (args.what.startsWith("grptsk_")) return getRoster(args, ctx);
+	const hint = args.what.startsWith("sub_") ? "a subtask is read through its parent: sp get tsk_…" : args.what.startsWith("sbm_") ? "a single submission has no read endpoint; find it in the listing: sp get submissions --since … --format json" : "expected tasks, submissions, a tsk_ id, or a grptsk_ id";
+	return Effect.fail(new UserError({ message: `cannot read '${args.what}': ${hint}` }));
+})).pipe(Command.withDescription("Read what came back: 'tasks' or 'submissions' for filtered listings, a tsk_ id for one task with its subtasks, a grptsk_ id for a group's per-recipient roster."));
+//#endregion
 //#region src/input-spec.ts
 const SETTING_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
 function looksLikeSetting(seg) {
@@ -2621,7 +2932,7 @@ const notifyCommand = Command.make("notify", {
 	shared: sharedOption$1,
 	format: formatOption$2,
 	noEncrypt: noEncryptOption$2,
-	topic: topicOption,
+	topic: topicOption$1,
 	"api-token": apiTokenOption,
 	password: passwordOption,
 	"base-url": baseUrlOption,
@@ -2812,7 +3123,7 @@ const putIntegrationWraps = (id, wraps) => Effect.gen(function* () {
 	yield* (yield* Api).put("integration wrap", `/v1/org/integrations/${encodeURIComponent(id)}/wraps`, { wraps });
 });
 const nameOption = Options.text("name").pipe(Options.withDescription("Human-readable label, shown in `sp integration list` and nowhere else."));
-const scopesOption = Options.text("scopes").pipe(Options.withDefault("send,events:read"), Options.withDescription("Comma-separated scopes (send, events:read, files:read). org:admin is refused — administration is a human act."));
+const scopesOption = Options.text("scopes").pipe(Options.withDefault("send,read"), Options.withDescription("Comma-separated scopes (send, read, files:read). org:admin is refused — administration is a human act."));
 const createCommand = Command.make("create", {
 	name: nameOption,
 	scopes: scopesOption,
@@ -3535,7 +3846,7 @@ const taskCommand = Command.make("task", {
 	shared: sharedOption,
 	expires: expiresOption,
 	format: formatOption$1,
-	topic: topicOption,
+	topic: topicOption$1,
 	"api-token": apiTokenOption,
 	password: passwordOption,
 	"base-url": baseUrlOption,
@@ -3841,7 +4152,7 @@ const subtaskCommand = Command.make("subtask", {
 	markdown: markdownOption,
 	"no-encrypt": noEncryptOption,
 	instance: instanceOption,
-	topic: topicOption,
+	topic: topicOption$1,
 	"api-token": apiTokenOption,
 	password: passwordOption,
 	"base-url": baseUrlOption,
@@ -4022,7 +4333,8 @@ const root = Command.make("simplepush").pipe(Command.withSubcommands([
 	notifyCommand,
 	taskCommand,
 	subtaskCommand,
-	cancelCommand
+	cancelCommand,
+	getCommand
 ]));
 const cli = Command.run(root, {
 	name: "Simplepush CLI",