granola-toolkit 0.9.0 → 0.11.0

package/README.md

@@ -32,6 +32,7 @@ Installed CLI:
 ```bash
 granola --help
 granola auth login
+granola meeting --help
 granola notes --help
 granola transcripts --help
 ```
@@ -41,6 +42,7 @@ Local build:
 ```bash
 vp pack
 node dist/cli.js --help
+node dist/cli.js meeting --help
 node dist/cli.js notes --help
 node dist/cli.js transcripts --help
 ```
@@ -49,6 +51,7 @@ You can also use the package scripts:
 
 ```bash
 npm run build
+npm run start -- meeting --help
 npm run notes -- --help
 npm run transcripts -- --help
 ```
@@ -72,6 +75,15 @@ node dist/cli.js transcripts --cache "$HOME/Library/Application Support/Granola/
 node dist/cli.js transcripts --format yaml --output ./transcripts-yaml
 ```
 
+Inspect individual meetings:
+
+```bash
+granola meeting list --limit 10
+granola meeting list --search planning
+granola meeting view 1234abcd
+granola meeting export 1234abcd --format yaml
+```
+
 ## How It Works
 
 ### Notes
@@ -121,6 +133,30 @@ Speaker labels are currently normalised to:
 
 Structured output formats are useful when you want to post-process exports in scripts instead of reading the default human-oriented Markdown or text files.
 
+### Meetings
+
+`meeting` combines the API-backed notes path with the local transcript cache so you can inspect one meeting at a time.
+
+The flow is:
+
+1. read a stored Granola session, or fall back to `supabase.json`
+2. fetch documents from Granola's API
+3. optionally load the local cache for transcript data
+4. resolve a meeting by full id or unique id prefix
+5. render either a list, a human-readable meeting view, or a machine-readable export bundle
+
+The human-readable `view` command shows:
+
+- meeting metadata
+- the selected notes content
+- transcript lines when the local cache is available
+
+The machine-readable `export` command includes:
+
+- a meeting summary
+- structured note data plus rendered Markdown
+- structured transcript data plus rendered transcript text when available
+
 ## Auth
 
 If you do not want to keep passing `--supabase`, import the desktop app session once:

package/dist/cli.js

@@ -5,12 +5,17 @@ import { mkdir, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
+import { NodeHtmlMarkdown } from "node-html-markdown";
 import { createHash } from "node:crypto";
 //#region src/utils.ts
 const INVALID_FILENAME_CHARS = /[<>:"/\\|?*]/g;
 const CONTROL_CHARACTERS = /\p{Cc}/gu;
 const MULTIPLE_UNDERSCORES = /_+/g;
 const MULTIPLE_BLANK_LINES = /\n{3,}/g;
+const htmlMarkdown = new NodeHtmlMarkdown({
+	bulletMarker: "-",
+	ignore: ["script", "style"]
+});
 function normaliseNewlines(value) {
 	return value.replace(/\r\n?/g, "\n");
 }
@@ -117,25 +122,9 @@ function formatTimestampForTranscript(timestamp) {
 	if (Number.isNaN(parsed.getTime())) return timestamp;
 	return parsed.toISOString().slice(11, 19);
 }
-function decodeHtmlEntities(value) {
-	return value.replaceAll("&nbsp;", " ").replaceAll("&amp;", "&").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&#39;", "'");
-}
-function htmlToMarkdownFallback(value) {
-	let output = normaliseNewlines(decodeHtmlEntities(value));
-	output = output.replace(/<br\s*\/?>/gi, "\n");
-	output = output.replace(/<li\b[^>]*>/gi, "- ");
-	output = output.replace(/<\/li>/gi, "\n");
-	output = output.replace(/<h1\b[^>]*>/gi, "# ");
-	output = output.replace(/<h2\b[^>]*>/gi, "## ");
-	output = output.replace(/<h3\b[^>]*>/gi, "### ");
-	output = output.replace(/<h4\b[^>]*>/gi, "#### ");
-	output = output.replace(/<h5\b[^>]*>/gi, "##### ");
-	output = output.replace(/<h6\b[^>]*>/gi, "###### ");
-	output = output.replace(/<\/(p|div|section|article|ul|ol|blockquote|h[1-6])>/gi, "\n\n");
-	output = output.replace(/<[^>]+>/g, "");
-	output = output.replace(/[ \t]+\n/g, "\n");
-	output = output.replace(MULTIPLE_BLANK_LINES, "\n\n");
-	return output.trim();
+function htmlToMarkdown(value) {
+	if (!value.trim()) return "";
+	return normaliseNewlines(htmlMarkdown.translate(value)).replace(/[ \t]+\n/g, "\n").replace(MULTIPLE_BLANK_LINES, "\n\n").trim();
 }
 function latestDocumentTimestamp(document) {
 	const candidates = [
@@ -445,6 +434,60 @@ async function logout() {
 	return 0;
 }
 //#endregion
+//#region src/cache.ts
+function parseCacheDocument(id, value) {
+	const record = asRecord(value);
+	if (!record) return;
+	return {
+		createdAt: stringValue(record.created_at),
+		id,
+		title: stringValue(record.title),
+		updatedAt: stringValue(record.updated_at)
+	};
+}
+function parseTranscriptSegments(value) {
+	if (!Array.isArray(value)) return;
+	return value.flatMap((segment) => {
+		const record = asRecord(segment);
+		if (!record) return [];
+		return [{
+			documentId: stringValue(record.document_id),
+			endTimestamp: stringValue(record.end_timestamp),
+			id: stringValue(record.id),
+			isFinal: Boolean(record.is_final),
+			source: stringValue(record.source),
+			startTimestamp: stringValue(record.start_timestamp),
+			text: stringValue(record.text)
+		}];
+	});
+}
+function parseCacheContents(contents) {
+	const outer = parseJsonString(contents);
+	if (!outer) throw new Error("failed to parse cache JSON");
+	const rawCache = outer.cache;
+	let cachePayload;
+	if (typeof rawCache === "string") cachePayload = parseJsonString(rawCache);
+	else cachePayload = asRecord(rawCache);
+	const state = cachePayload ? asRecord(cachePayload.state) : void 0;
+	if (!state) throw new Error("failed to parse cache state");
+	const rawDocuments = asRecord(state.documents) ?? {};
+	const rawTranscripts = asRecord(state.transcripts) ?? {};
+	const documents = {};
+	for (const [id, rawDocument] of Object.entries(rawDocuments)) {
+		const document = parseCacheDocument(id, rawDocument);
+		if (document) documents[id] = document;
+	}
+	const transcripts = {};
+	for (const [id, rawTranscript] of Object.entries(rawTranscripts)) {
+		const segments = parseTranscriptSegments(rawTranscript);
+		if (segments) transcripts[id] = segments;
+	}
+	return {
+		documents,
+		transcripts
+	};
+}
+//#endregion
 //#region src/client/parsers.ts
 function parseProseMirrorDoc(value, options = {}) {
 	if (value == null) return;
@@ -583,6 +626,22 @@ var AuthenticatedHttpClient = class {
 	}
 };
 //#endregion
+//#region src/client/default.ts
+async function createDefaultGranolaApiClient(config, logger = console) {
+	const sessionStore = createDefaultSessionStore();
+	const storedSession = await sessionStore.readSession();
+	if (!storedSession && !config.supabase) throw new Error(`supabase.json not found. Pass --supabase or create .granola.toml. Expected locations include: ${granolaSupabaseCandidates().join(", ")}`);
+	if (!storedSession && config.supabase && !existsSync(config.supabase)) throw new Error(`supabase.json not found: ${config.supabase}`);
+	return new GranolaApiClient(new AuthenticatedHttpClient({
+		logger,
+		tokenProvider: storedSession ? new StoredSessionTokenProvider(sessionStore, { source: config.supabase && existsSync(config.supabase) ? new SupabaseFileSessionSource(config.supabase) : void 0 }) : new CachedTokenProvider(new SupabaseFileTokenSource(config.supabase), new NoopTokenStore())
+	}));
+}
+async function loadOptionalGranolaCache(cacheFile) {
+	if (!cacheFile || !existsSync(cacheFile)) return;
+	return parseCacheContents(await readFile(cacheFile, "utf8"));
+}
+//#endregion
 //#region src/config.ts
 function pickString(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
@@ -928,7 +987,7 @@ function selectNoteContent(document) {
 		content: lastViewedPanel,
 		source: "lastViewedPanel.content"
 	};
-	const originalContent = htmlToMarkdownFallback(document.lastViewedPanel?.originalContent ?? "").trim();
+	const originalContent = htmlToMarkdown(document.lastViewedPanel?.originalContent ?? "").trim();
 	if (originalContent) return {
 		content: originalContent,
 		source: "lastViewedPanel.originalContent"
@@ -1017,131 +1076,6 @@ async function writeNotes(documents, outputDir, format = "markdown") {
 	});
 }
 //#endregion
-//#region src/commands/shared.ts
-function debug(enabled, ...values) {
-	if (enabled) console.error("[debug]", ...values);
-}
-//#endregion
-//#region src/commands/notes.ts
-function notesHelp() {
-	return `Granola notes
-
-Usage:
-  granola notes [options]
-
-Options:
-  --format <value>    Output format: markdown, json, yaml, raw (default: markdown)
-  --output <path>     Output directory for note files (default: ./notes)
-  --timeout <value>   Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
-  --supabase <path>   Path to supabase.json
-  --debug             Enable debug logging
-  --config <path>     Path to .granola.toml
-  -h, --help          Show help
-`;
-}
-const notesCommand = {
-	description: "Export Granola notes",
-	flags: {
-		format: { type: "string" },
-		help: { type: "boolean" },
-		output: { type: "string" },
-		timeout: { type: "string" }
-	},
-	help: notesHelp,
-	name: "notes",
-	async run({ commandFlags, globalFlags }) {
-		const config = await loadConfig({
-			globalFlags,
-			subcommandFlags: commandFlags
-		});
-		const sessionStore = createDefaultSessionStore();
-		const storedSession = await sessionStore.readSession();
-		if (!storedSession && !config.supabase) throw new Error(`supabase.json not found. Pass --supabase or create .granola.toml. Expected locations include: ${granolaSupabaseCandidates().join(", ")}`);
-		if (!storedSession && config.supabase && !existsSync(config.supabase)) throw new Error(`supabase.json not found: ${config.supabase}`);
-		debug(config.debug, "using config", config.configFileUsed ?? "(none)");
-		debug(config.debug, "supabase", config.supabase);
-		debug(config.debug, "timeoutMs", config.notes.timeoutMs);
-		debug(config.debug, "output", config.notes.output);
-		const format = resolveNoteFormat(commandFlags.format);
-		debug(config.debug, "format", format);
-		console.log("Fetching documents from Granola API...");
-		const tokenProvider = storedSession ? new StoredSessionTokenProvider(sessionStore, { source: config.supabase && existsSync(config.supabase) ? new SupabaseFileSessionSource(config.supabase) : void 0 }) : new CachedTokenProvider(new SupabaseFileTokenSource(config.supabase), new NoopTokenStore());
-		const documents = await new GranolaApiClient(new AuthenticatedHttpClient({
-			logger: console,
-			tokenProvider
-		})).listDocuments({ timeoutMs: config.notes.timeoutMs });
-		console.log(`Exporting ${documents.length} notes to ${config.notes.output}...`);
-		const written = await writeNotes(documents, config.notes.output, format);
-		console.log("✓ Export completed successfully");
-		debug(config.debug, "notes written", written);
-		return 0;
-	}
-};
-function resolveNoteFormat(value) {
-	switch (value) {
-		case void 0: return "markdown";
-		case "json":
-		case "markdown":
-		case "raw":
-		case "yaml": return value;
-		default: throw new Error("invalid notes format: expected markdown, json, yaml, or raw");
-	}
-}
-//#endregion
-//#region src/cache.ts
-function parseCacheDocument(id, value) {
-	const record = asRecord(value);
-	if (!record) return;
-	return {
-		createdAt: stringValue(record.created_at),
-		id,
-		title: stringValue(record.title),
-		updatedAt: stringValue(record.updated_at)
-	};
-}
-function parseTranscriptSegments(value) {
-	if (!Array.isArray(value)) return;
-	return value.flatMap((segment) => {
-		const record = asRecord(segment);
-		if (!record) return [];
-		return [{
-			documentId: stringValue(record.document_id),
-			endTimestamp: stringValue(record.end_timestamp),
-			id: stringValue(record.id),
-			isFinal: Boolean(record.is_final),
-			source: stringValue(record.source),
-			startTimestamp: stringValue(record.start_timestamp),
-			text: stringValue(record.text)
-		}];
-	});
-}
-function parseCacheContents(contents) {
-	const outer = parseJsonString(contents);
-	if (!outer) throw new Error("failed to parse cache JSON");
-	const rawCache = outer.cache;
-	let cachePayload;
-	if (typeof rawCache === "string") cachePayload = parseJsonString(rawCache);
-	else cachePayload = asRecord(rawCache);
-	const state = cachePayload ? asRecord(cachePayload.state) : void 0;
-	if (!state) throw new Error("failed to parse cache state");
-	const rawDocuments = asRecord(state.documents) ?? {};
-	const rawTranscripts = asRecord(state.transcripts) ?? {};
-	const documents = {};
-	for (const [id, rawDocument] of Object.entries(rawDocuments)) {
-		const document = parseCacheDocument(id, rawDocument);
-		if (document) documents[id] = document;
-	}
-	const transcripts = {};
-	for (const [id, rawTranscript] of Object.entries(rawTranscripts)) {
-		const segments = parseTranscriptSegments(rawTranscript);
-		if (segments) transcripts[id] = segments;
-	}
-	return {
-		documents,
-		transcripts
-	};
-}
-//#endregion
 //#region src/transcripts.ts
 function transcriptSegmentKey(segment) {
 	if (segment.id) return `id:${segment.id}`;
@@ -1174,7 +1108,9 @@ function normaliseTranscriptSegments(segments) {
 		const current = selected.get(key);
 		selected.set(key, preferredTranscriptSegment(current, segment));
 	}
-	return [...selected.values()].sort(compareTranscriptSegments);
+	const resolved = [...selected.values()].sort(compareTranscriptSegments);
+	if (resolved.some((segment) => segment.isFinal)) return resolved.filter((segment) => segment.isFinal);
+	return resolved;
 }
 function buildTranscriptExport(document, segments, rawSegments = segments) {
 	const renderedSegments = segments.map((segment) => ({
@@ -1275,6 +1211,398 @@ async function writeTranscripts(cacheData, outputDir, format = "text") {
 	});
 }
 //#endregion
+//#region src/meetings.ts
+function parseTimestamp(value) {
+	if (!value.trim()) return;
+	const timestamp = Date.parse(value);
+	return Number.isNaN(timestamp) ? void 0 : timestamp;
+}
+function compareTimestampsDescending(left, right) {
+	const leftTimestamp = parseTimestamp(left);
+	const rightTimestamp = parseTimestamp(right);
+	if (leftTimestamp != null && rightTimestamp != null) return rightTimestamp - leftTimestamp;
+	if (leftTimestamp != null) return -1;
+	if (rightTimestamp != null) return 1;
+	return compareStrings(right, left);
+}
+function compareMeetingDocuments(left, right) {
+	return compareTimestampsDescending(latestDocumentTimestamp(left), latestDocumentTimestamp(right)) || compareTimestampsDescending(left.createdAt, right.createdAt) || compareStrings(left.title || left.id, right.title || right.id) || compareStrings(left.id, right.id);
+}
+function serialiseNote(note) {
+	return {
+		content: note.content,
+		contentSource: note.contentSource,
+		createdAt: note.createdAt,
+		id: note.id,
+		tags: [...note.tags],
+		title: note.title,
+		updatedAt: note.updatedAt
+	};
+}
+function serialiseTranscript(transcript) {
+	return {
+		createdAt: transcript.createdAt,
+		id: transcript.id,
+		segments: transcript.segments.map((segment) => ({ ...segment })),
+		title: transcript.title,
+		updatedAt: transcript.updatedAt
+	};
+}
+function cacheDocumentForMeeting(document, cacheData) {
+	return cacheData?.documents[document.id] ?? {
+		createdAt: document.createdAt,
+		id: document.id,
+		title: document.title,
+		updatedAt: latestDocumentTimestamp(document)
+	};
+}
+function buildMeetingTranscript(document, cacheData) {
+	if (!cacheData) return {
+		loaded: false,
+		segmentCount: 0,
+		transcript: null,
+		transcriptText: null
+	};
+	const rawSegments = cacheData.transcripts[document.id] ?? [];
+	const normalisedSegments = normaliseTranscriptSegments(rawSegments);
+	if (normalisedSegments.length === 0) return {
+		loaded: true,
+		segmentCount: 0,
+		transcript: null,
+		transcriptText: null
+	};
+	const transcript = buildTranscriptExport(cacheDocumentForMeeting(document, cacheData), normalisedSegments, rawSegments);
+	return {
+		loaded: true,
+		segmentCount: transcript.segments.length,
+		transcript: serialiseTranscript(transcript),
+		transcriptText: renderTranscriptExport(transcript, "text")
+	};
+}
+function matchesMeetingSearch(document, search) {
+	const query = search.trim().toLowerCase();
+	if (!query) return true;
+	return [
+		document.id,
+		document.title,
+		...document.tags
+	].some((value) => value.toLowerCase().includes(query));
+}
+function truncate(value, width) {
+	if (value.length <= width) return value.padEnd(width);
+	return `${value.slice(0, Math.max(0, width - 1))}…`;
+}
+function formatMeetingDate(value) {
+	return value.trim().slice(0, 10) || "-";
+}
+function formatTranscriptStatus(meeting) {
+	if (!meeting.transcriptLoaded) return "n/a";
+	if (meeting.transcriptSegmentCount === 0) return "none";
+	return String(meeting.transcriptSegmentCount);
+}
+function formatTranscriptLines(transcript) {
+	if (!transcript || transcript.segments.length === 0) return "";
+	return transcript.segments.map((segment) => `[${formatTimestampForTranscript(segment.startTimestamp)}] ${segment.speaker}: ${segment.text}`).join("\n");
+}
+function buildMeetingSummary(document, cacheData) {
+	const note = buildNoteExport(document);
+	const transcript = buildMeetingTranscript(document, cacheData);
+	return {
+		createdAt: document.createdAt,
+		id: document.id,
+		noteContentSource: note.contentSource,
+		tags: [...document.tags],
+		title: document.title,
+		transcriptLoaded: transcript.loaded,
+		transcriptSegmentCount: transcript.segmentCount,
+		updatedAt: latestDocumentTimestamp(document)
+	};
+}
+function buildMeetingRecord(document, cacheData) {
+	const note = buildNoteExport(document);
+	const transcript = buildMeetingTranscript(document, cacheData);
+	return {
+		meeting: {
+			createdAt: document.createdAt,
+			id: document.id,
+			noteContentSource: note.contentSource,
+			tags: [...document.tags],
+			title: document.title,
+			transcriptLoaded: transcript.loaded,
+			transcriptSegmentCount: transcript.segmentCount,
+			updatedAt: latestDocumentTimestamp(document)
+		},
+		note: serialiseNote(note),
+		noteMarkdown: renderNoteExport(note, "markdown"),
+		transcript: transcript.transcript,
+		transcriptText: transcript.transcriptText
+	};
+}
+function listMeetings(documents, options = {}) {
+	const limit = options.limit ?? 20;
+	return documents.filter((document) => options.search ? matchesMeetingSearch(document, options.search) : true).sort(compareMeetingDocuments).slice(0, limit).map((document) => buildMeetingSummary(document, options.cacheData));
+}
+function resolveMeeting(documents, id) {
+	const exactMatch = documents.find((document) => document.id === id);
+	if (exactMatch) return exactMatch;
+	const matches = documents.filter((document) => document.id.startsWith(id));
+	if (matches.length === 1) return matches[0];
+	if (matches.length > 1) {
+		const sample = matches.slice(0, 5).map((document) => document.id.slice(0, 8)).join(", ");
+		throw new Error(`ambiguous meeting id: ${id} matches ${matches.length} meetings (${sample})`);
+	}
+	throw new Error(`meeting not found: ${id}`);
+}
+function renderMeetingList(meetings, format = "text") {
+	switch (format) {
+		case "json": return toJson(meetings);
+		case "yaml": return toYaml(meetings);
+		case "text": break;
+	}
+	if (meetings.length === 0) return "No meetings found\n";
+	const lines = [`${"ID".padEnd(10)} ${"DATE".padEnd(10)} ${"TITLE".padEnd(42)} ${"NOTE".padEnd(18)} TRANSCRIPT`, `${"-".repeat(10)} ${"-".repeat(10)} ${"-".repeat(42)} ${"-".repeat(18)} ${"-".repeat(10)}`];
+	for (const meeting of meetings) lines.push([
+		meeting.id.slice(0, 8).padEnd(10),
+		formatMeetingDate(meeting.updatedAt || meeting.createdAt).padEnd(10),
+		truncate(meeting.title || meeting.id, 42),
+		truncate(meeting.noteContentSource, 18),
+		formatTranscriptStatus(meeting)
+	].join(" "));
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+function renderMeetingView(record, format = "text") {
+	switch (format) {
+		case "json": return toJson(record);
+		case "yaml": return toYaml(record);
+		case "text": break;
+	}
+	const tags = record.meeting.tags.length > 0 ? record.meeting.tags.join(", ") : "(none)";
+	const transcriptStatus = !record.meeting.transcriptLoaded ? "cache not loaded" : record.meeting.transcriptSegmentCount === 0 ? "no transcript segments" : `${record.meeting.transcriptSegmentCount} segment(s)`;
+	return `${[
+		`# ${record.meeting.title || record.meeting.id}`,
+		"",
+		`ID: ${record.meeting.id}`,
+		`Created: ${record.meeting.createdAt || "-"}`,
+		`Updated: ${record.meeting.updatedAt || "-"}`,
+		`Tags: ${tags}`,
+		`Note source: ${record.meeting.noteContentSource}`,
+		`Transcript: ${transcriptStatus}`,
+		"",
+		"## Notes",
+		"",
+		record.note.content.trim() || "(no notes)",
+		"",
+		"## Transcript",
+		"",
+		formatTranscriptLines(record.transcript) || (record.meeting.transcriptLoaded ? "(no transcript segments)" : "(Granola cache not loaded)"),
+		""
+	].join("\n").trimEnd()}\n`;
+}
+function renderMeetingExport(record, format = "json") {
+	switch (format) {
+		case "json": return toJson(record);
+		case "yaml": return toYaml(record);
+	}
+}
+//#endregion
+//#region src/commands/shared.ts
+function debug(enabled, ...values) {
+	if (enabled) console.error("[debug]", ...values);
+}
+//#endregion
+//#region src/commands/meeting.ts
+function meetingHelp() {
+	return `Granola meeting
+
+Usage:
+  granola meeting <list|view|export> [options]
+
+Subcommands:
+  list                List meetings from the Granola API
+  view <id>           Show a single meeting with notes and transcript text
+  export <id>         Export a single meeting as JSON or YAML
+
+Options:
+  --cache <path>      Path to Granola cache JSON for transcript data
+  --format <value>    list/view: text, json, yaml; export: json, yaml
+  --limit <n>         Number of meetings for list (default: 20)
+  --search <query>    Filter list by title, id, or tag
+  --timeout <value>   Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
+  --supabase <path>   Path to supabase.json
+  --debug             Enable debug logging
+  --config <path>     Path to .granola.toml
+  -h, --help          Show help
+`;
+}
+function resolveListFormat(value) {
+	switch (value) {
+		case void 0: return "text";
+		case "json":
+		case "text":
+		case "yaml": return value;
+		default: throw new Error("invalid meeting format: expected text, json, or yaml");
+	}
+}
+function resolveViewFormat(value) {
+	switch (value) {
+		case void 0: return "text";
+		case "json":
+		case "text":
+		case "yaml": return value;
+		default: throw new Error("invalid meeting format: expected text, json, or yaml");
+	}
+}
+function resolveExportFormat(value) {
+	switch (value) {
+		case void 0: return "json";
+		case "json":
+		case "yaml": return value;
+		default: throw new Error("invalid meeting export format: expected json or yaml");
+	}
+}
+function parseLimit(value) {
+	if (value === void 0) return 20;
+	if (typeof value !== "string" || !/^\d+$/.test(value)) throw new Error("invalid meeting limit: expected a positive integer");
+	const limit = Number(value);
+	if (!Number.isInteger(limit) || limit < 1) throw new Error("invalid meeting limit: expected a positive integer");
+	return limit;
+}
+const meetingCommand = {
+	description: "Inspect and export individual Granola meetings",
+	flags: {
+		cache: { type: "string" },
+		format: { type: "string" },
+		help: { type: "boolean" },
+		limit: { type: "string" },
+		search: { type: "string" },
+		timeout: { type: "string" }
+	},
+	help: meetingHelp,
+	name: "meeting",
+	async run({ commandArgs, commandFlags, globalFlags }) {
+		const [action, id] = commandArgs;
+		switch (action) {
+			case "list": return await list(commandFlags, globalFlags);
+			case "view":
+				if (!id) throw new Error("meeting view requires an id");
+				return await view(id, commandFlags, globalFlags);
+			case "export":
+				if (!id) throw new Error("meeting export requires an id");
+				return await exportMeeting(id, commandFlags, globalFlags);
+			case void 0:
+				console.log(meetingHelp());
+				return 1;
+			default: throw new Error("invalid meeting command: expected list, view, or export");
+		}
+	}
+};
+async function loadMeetingData(commandFlags, globalFlags) {
+	const config = await loadConfig({
+		globalFlags,
+		subcommandFlags: commandFlags
+	});
+	if (config.transcripts.cacheFile && !existsSync(config.transcripts.cacheFile)) throw new Error(`Granola cache file not found: ${config.transcripts.cacheFile}`);
+	debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+	debug(config.debug, "supabase", config.supabase);
+	debug(config.debug, "cacheFile", config.transcripts.cacheFile || "(none)");
+	debug(config.debug, "timeoutMs", config.notes.timeoutMs);
+	const granolaClient = await createDefaultGranolaApiClient(config);
+	return {
+		cacheData: await loadOptionalGranolaCache(config.transcripts.cacheFile),
+		config,
+		granolaClient
+	};
+}
+async function list(commandFlags, globalFlags) {
+	const format = resolveListFormat(commandFlags.format);
+	const limit = parseLimit(commandFlags.limit);
+	const search = typeof commandFlags.search === "string" ? commandFlags.search : void 0;
+	const { cacheData, config, granolaClient } = await loadMeetingData(commandFlags, globalFlags);
+	console.log("Fetching meetings from Granola API...");
+	const meetings = listMeetings(await granolaClient.listDocuments({ timeoutMs: config.notes.timeoutMs }), {
+		cacheData,
+		limit,
+		search
+	});
+	console.log(renderMeetingList(meetings, format).trimEnd());
+	return 0;
+}
+async function view(id, commandFlags, globalFlags) {
+	const format = resolveViewFormat(commandFlags.format);
+	const { cacheData, config, granolaClient } = await loadMeetingData(commandFlags, globalFlags);
+	console.log("Fetching meeting from Granola API...");
+	const meeting = buildMeetingRecord(resolveMeeting(await granolaClient.listDocuments({ timeoutMs: config.notes.timeoutMs }), id), cacheData);
+	console.log(renderMeetingView(meeting, format).trimEnd());
+	return 0;
+}
+async function exportMeeting(id, commandFlags, globalFlags) {
+	const format = resolveExportFormat(commandFlags.format);
+	const { cacheData, config, granolaClient } = await loadMeetingData(commandFlags, globalFlags);
+	console.log("Fetching meeting from Granola API...");
+	const meeting = buildMeetingRecord(resolveMeeting(await granolaClient.listDocuments({ timeoutMs: config.notes.timeoutMs }), id), cacheData);
+	console.log(renderMeetingExport(meeting, format).trimEnd());
+	return 0;
+}
+//#endregion
+//#region src/commands/notes.ts
+function notesHelp() {
+	return `Granola notes
+
+Usage:
+  granola notes [options]
+
+Options:
+  --format <value>    Output format: markdown, json, yaml, raw (default: markdown)
+  --output <path>     Output directory for note files (default: ./notes)
+  --timeout <value>   Request timeout, e.g. 2m, 30s, 120000 (default: 2m)
+  --supabase <path>   Path to supabase.json
+  --debug             Enable debug logging
+  --config <path>     Path to .granola.toml
+  -h, --help          Show help
+`;
+}
+const notesCommand = {
+	description: "Export Granola notes",
+	flags: {
+		format: { type: "string" },
+		help: { type: "boolean" },
+		output: { type: "string" },
+		timeout: { type: "string" }
+	},
+	help: notesHelp,
+	name: "notes",
+	async run({ commandFlags, globalFlags }) {
+		const config = await loadConfig({
+			globalFlags,
+			subcommandFlags: commandFlags
+		});
+		debug(config.debug, "using config", config.configFileUsed ?? "(none)");
+		debug(config.debug, "supabase", config.supabase);
+		debug(config.debug, "timeoutMs", config.notes.timeoutMs);
+		debug(config.debug, "output", config.notes.output);
+		const format = resolveNoteFormat(commandFlags.format);
+		debug(config.debug, "format", format);
+		const granolaClient = await createDefaultGranolaApiClient(config);
+		console.log("Fetching documents from Granola API...");
+		const documents = await granolaClient.listDocuments({ timeoutMs: config.notes.timeoutMs });
+		console.log(`Exporting ${documents.length} notes to ${config.notes.output}...`);
+		const written = await writeNotes(documents, config.notes.output, format);
+		console.log("✓ Export completed successfully");
+		debug(config.debug, "notes written", written);
+		return 0;
+	}
+};
+function resolveNoteFormat(value) {
+	switch (value) {
+		case void 0: return "markdown";
+		case "json":
+		case "markdown":
+		case "raw":
+		case "yaml": return value;
+		default: throw new Error("invalid notes format: expected markdown, json, yaml, or raw");
+	}
+}
+//#endregion
 //#region src/commands/transcripts.ts
 function transcriptsHelp() {
 	return `Granola transcripts
@@ -1337,6 +1665,7 @@ function resolveTranscriptFormat(value) {
 //#region src/commands/index.ts
 const commands = [
 	authCommand,
+	meetingCommand,
 	notesCommand,
 	transcriptsCommand
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granola-toolkit",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "CLI toolkit for exporting and working with Granola notes and transcripts",
   "keywords": [
     "cli",
@@ -49,6 +49,9 @@
     "typecheck": "vp exec tsc --noEmit",
     "prepare": "vp config"
   },
+  "dependencies": {
+    "node-html-markdown": "^2.0.0"
+  },
   "devDependencies": {
     "@types/node": "^25.5.2",
     "typescript": "^5.9.3",