Skip to content

A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search

feat(cli): expose assets and readable conent in the CLI

Mohamed Bassema2968718aa33
diff --git a/apps/cli/src/commands/assets.ts b/apps/cli/src/commands/assets.ts
new file mode 100644
index 00000000..15adc030
--- /dev/null
+++ b/apps/cli/src/commands/assets.ts
@@ -0,0 +1,117 @@
+import { constants, createWriteStream } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { getGlobalOptions } from "@/lib/globals";
+import { getResponseError } from "@/lib/http";
+import { printObject, printStatusMessage } from "@/lib/output";
+import { Command } from "@commander-js/extra-typings";
+
+export const assetsCmd = new Command()
+ .name("assets")
+ .description("manipulating assets");
+
+async function pathExists(filePath: string) {
+ try {
+ await fs.access(filePath);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function* readResponseBody(body: ReadableStream<Uint8Array>) {
+ const reader = body.getReader();
+ try {
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) {
+ return;
+ }
+ yield value;
+ }
+ } finally {
+ reader.releaseLock();
+ }
+}
+
+assetsCmd
+ .command("download")
+ .description("download an asset to a file")
+ .argument("<id>", "the id of the asset to download")
+ .requiredOption("-o, --output <file>", "the destination file path")
+ .option("-f, --force", "overwrite the destination file if it already exists")
+ .action(async (id, opts) => {
+ const globals = getGlobalOptions();
+ const outputPath = path.resolve(opts.output);
+
+ try {
+ if (!opts.force && (await pathExists(outputPath))) {
+ throw new Error(
+ `Destination file already exists at ${outputPath}. Re-run with --force to overwrite it.`,
+ );
+ }
+
+ const response = await fetch(
+ `${globals.serverAddr}/api/v1/assets/${encodeURIComponent(id)}`,
+ {
+ headers: {
+ authorization: `Bearer ${globals.apiKey}`,
+ },
+ },
+ );
+ if (!response.ok) {
+ throw new Error(await getResponseError(response));
+ }
+ if (!response.body) {
+ throw new Error("The server returned an empty response body");
+ }
+
+ await fs.mkdir(path.dirname(outputPath), { recursive: true });
+ const temporaryPath = path.join(
+ path.dirname(outputPath),
+ `.${path.basename(outputPath)}.${process.pid}.${Date.now()}.tmp`,
+ );
+
+ try {
+ await pipeline(
+ readResponseBody(response.body),
+ createWriteStream(temporaryPath, { flags: "wx" }),
+ );
+ if (opts.force) {
+ await fs.rename(temporaryPath, outputPath);
+ } else {
+ await fs.copyFile(temporaryPath, outputPath, constants.COPYFILE_EXCL);
+ await fs.unlink(temporaryPath);
+ }
+ } catch (error) {
+ await fs.rm(temporaryPath, { force: true });
+ throw error;
+ }
+
+ const size = (await fs.stat(outputPath)).size;
+ const result = {
+ assetId: id,
+ output: outputPath,
+ contentType: response.headers.get("content-type"),
+ size,
+ };
+
+ if (globals.json) {
+ printObject(result);
+ } else {
+ printStatusMessage(
+ true,
+ `Downloaded asset "${id}" to ${outputPath} (${size} bytes)`,
+ );
+ }
+ } catch (error) {
+ printStatusMessage(
+ false,
+ `Failed to download asset "${id}". Reason: ${
+ error instanceof Error ? error.message : error
+ }`,
+ );
+ process.exitCode = 1;
+ }
+ });
diff --git a/apps/cli/src/commands/bookmarks.ts b/apps/cli/src/commands/bookmarks.ts
index 0cbd1a09..17f1dd5d 100644
--- a/apps/cli/src/commands/bookmarks.ts
+++ b/apps/cli/src/commands/bookmarks.ts
@@ -2,6 +2,7 @@ import * as fs from "node:fs";
import * as path from "node:path";
import { addToList } from "@/commands/lists";
import { getGlobalOptions } from "@/lib/globals";
+import { getResponseError } from "@/lib/http";
import {
printError,
printObject,
@@ -15,8 +16,10 @@ import chalk from "chalk";
import type { ZBookmark } from "@karakeep/shared/types/bookmarks";
import {
BookmarkTypes,
+ MAX_READABLE_CONTENT_MAX_CHARS,
MAX_NUM_BOOKMARKS_PER_PAGE,
} from "@karakeep/shared/types/bookmarks";
+import type { ZBookmarkReadableContentFormat } from "@karakeep/shared/types/bookmarks";
export const bookmarkCmd = new Command()
.name("bookmarks")
@@ -80,13 +83,19 @@ function printBookmarkDetail(b: ZBookmark) {
console.log(b.content.text);
}
+ if (b.content.type === BookmarkTypes.ASSET) {
+ console.log(chalk.dim(` Asset Id: ${b.content.assetId}`));
+ }
+
if (b.assets.length > 0) {
const serverAddr = getGlobalOptions().serverAddr;
console.log(` Attachments:`);
for (const asset of b.assets) {
const name = asset.fileName ?? asset.assetType;
const assetUrl = `${serverAddr}/api/assets/${asset.id}`;
- console.log(` - ${name} ${chalk.cyan(assetUrl)}`);
+ console.log(` - ${name}`);
+ console.log(chalk.dim(` Id: ${asset.id}`));
+ console.log(` URL: ${chalk.cyan(assetUrl)}`);
}
}
console.log();
@@ -310,6 +319,107 @@ bookmarkCmd
.catch(printError(`Failed to get the bookmark with id "${id}"`));
});
+interface ReadableContentResponse {
+ bookmarkId: string;
+ bookmarkType: "link" | "text" | "asset";
+ format: ZBookmarkReadableContentFormat;
+ content: string;
+ contentVersion: string;
+ range: {
+ start: number;
+ end: number;
+ total: number;
+ };
+ nextCursor: string | null;
+ truncated: boolean;
+}
+
+function parseReadableContentFormat(
+ value: string,
+): ZBookmarkReadableContentFormat {
+ if (value !== "markdown" && value !== "text") {
+ throw new Error("format must be one of: markdown, text");
+ }
+ return value;
+}
+
+function parseMaxChars(value: string): number {
+ const maxChars = Number(value);
+ if (
+ !Number.isInteger(maxChars) ||
+ maxChars < 1 ||
+ maxChars > MAX_READABLE_CONTENT_MAX_CHARS
+ ) {
+ throw new Error(
+ `max-chars must be an integer between 1 and ${MAX_READABLE_CONTENT_MAX_CHARS}`,
+ );
+ }
+ return maxChars;
+}
+
+bookmarkCmd
+ .command("content")
+ .description("fetch a bounded chunk of readable bookmark content")
+ .argument("<id>", "the id of the bookmark")
+ .option(
+ "--format <format>",
+ "content format (markdown or text)",
+ parseReadableContentFormat,
+ )
+ .option(
+ "--max-chars <count>",
+ `maximum Unicode characters to fetch (max ${MAX_READABLE_CONTENT_MAX_CHARS})`,
+ parseMaxChars,
+ )
+ .option("--cursor <cursor>", "continuation cursor from a previous response")
+ .action(async (id, opts) => {
+ const globals = getGlobalOptions();
+ const url = new URL(
+ `${globals.serverAddr}/api/v1/bookmarks/${encodeURIComponent(id)}/content`,
+ );
+ if (opts.format) {
+ url.searchParams.set("format", opts.format);
+ }
+ if (opts.maxChars) {
+ url.searchParams.set("maxChars", opts.maxChars.toString());
+ }
+ if (opts.cursor) {
+ url.searchParams.set("cursor", opts.cursor);
+ }
+
+ try {
+ const response = await fetch(url, {
+ headers: {
+ authorization: `Bearer ${globals.apiKey}`,
+ },
+ });
+ if (!response.ok) {
+ throw new Error(await getResponseError(response));
+ }
+
+ const result = (await response.json()) as ReadableContentResponse;
+ if (globals.json) {
+ printObject(result);
+ } else {
+ process.stdout.write(result.content);
+ if (result.content && !result.content.endsWith("\n")) {
+ process.stdout.write("\n");
+ }
+ if (result.nextCursor) {
+ console.error(`Next cursor: ${result.nextCursor}`);
+ }
+ }
+ } catch (error) {
+ printStatusMessage(
+ false,
+ `Failed to fetch readable content for bookmark "${id}". Reason: ${
+ error instanceof Error ? error.message : error
+ }`,
+ );
+ process.exitCode = 1;
+ }
+ });
+
function printTagMessage(
tags: { tagName: string }[],
bookmarkId: string,
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 4c5d0f40..10b2ef41 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -1,4 +1,5 @@
import { adminCmd } from "@/commands/admin";
+import { assetsCmd } from "@/commands/assets";
import { authCmd } from "@/commands/auth";
import { bookmarkCmd } from "@/commands/bookmarks";
import { dumpCmd } from "@/commands/dump";
@@ -73,6 +74,7 @@ const program = new Command()
);
program.addCommand(adminCmd);
+program.addCommand(assetsCmd);
program.addCommand(authCmd);
program.addCommand(bookmarkCmd);
program.addCommand(highlightsCmd);
diff --git a/apps/cli/src/lib/http.ts b/apps/cli/src/lib/http.ts
new file mode 100644
index 00000000..858285ac
--- /dev/null
+++ b/apps/cli/src/lib/http.ts
@@ -0,0 +1,24 @@
+export async function getResponseError(response: Response): Promise<string> {
+ let detail: string | undefined;
+
+ try {
+ const body = await response.text();
+ if (body) {
+ try {
+ const parsed = JSON.parse(body) as {
+ error?: unknown;
+ message?: unknown;
+ };
+ const message = parsed.message ?? parsed.error;
+ detail = typeof message === "string" ? message : body;
+ } catch {
+ detail = body;
+ }
+ }
+ } catch {
+ // The status still provides a useful error if the response body is unreadable.
+ }
+
+ const status = `HTTP ${response.status} ${response.statusText}`.trim();
+ return detail ? `${status}: ${detail}` : status;
+}