init

ts/packages/cli/package.json

@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@trustgraph/base": "workspace:*",
-    "@trustgraph/mcp": "workspace:*",
+    "@trustgraph/client": "workspace:*",
     "commander": "^13.1.0",
     "ws": "^8.18.0"
   },

ts/packages/cli/src/commands/agent.ts

@@ -17,18 +17,32 @@ export function registerAgentCommands(program: Command): void {
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request("agent", { question }, {
-          flowId: opts.flow,
-          onChunk: (chunk) => {
-            const c = chunk as { answer?: string };
-            if (c.answer) process.stdout.write(c.answer);
-          },
-        });
+        const flow = socket.flow(opts.flow);
 
-        const r = resp as { answer?: string };
-        if (r.answer) console.log(r.answer);
+        await new Promise<void>((resolve, reject) => {
+          flow.agent(
+            question,
+            (chunk) => {
+              // think — show thought process
+              if (chunk) process.stderr.write(chunk);
+            },
+            (chunk) => {
+              // observe — show observations
+              if (chunk) process.stderr.write(chunk);
+            },
+            (chunk, complete) => {
+              // answer — print to stdout
+              if (chunk) process.stdout.write(chunk);
+              if (complete) {
+                process.stdout.write("\n");
+                resolve();
+              }
+            },
+            (err) => reject(new Error(err)),
+          );
+        });
       } finally {
-        await socket.close();
+        socket.close();
       }
     });
 }

ts/packages/cli/src/commands/config.ts

@@ -20,62 +20,96 @@ export function registerConfigCommands(program: Command): void {
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request("config", { operation: "config" });
+        const cfg = socket.config();
+        const resp = await cfg.getConfigAll();
         console.log(JSON.stringify(resp, null, 2));
       } finally {
-        await socket.close();
+        socket.close();
       }
     });
 
   config
     .command("get")
     .description("Get a configuration value")
-    .argument("<key>", "Config key")
+    .argument("<key>", "Config key (format: type/key)")
     .action(async (key: string, _opts, cmd) => {
       const opts = getOpts(cmd);
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request("config", { operation: "get", keys: [key] });
+        const cfg = socket.config();
+        // Support "type/key" format; fall back to using the whole string as key
+        const parts = key.split("/");
+        const configKey =
+          parts.length >= 2
+            ? { type: parts[0], key: parts.slice(1).join("/") }
+            : { type: "config", key };
+        const resp = await cfg.getConfig([configKey]);
         console.log(JSON.stringify(resp, null, 2));
       } finally {
-        await socket.close();
+        socket.close();
       }
     });
 
   config
     .command("set")
     .description("Set a configuration value")
-    .argument("<key>", "Config key")
+    .argument("<key>", "Config key (format: type/key)")
     .argument("<value>", "Config value (JSON)")
     .action(async (key: string, value: string, _opts, cmd) => {
       const opts = getOpts(cmd);
       const socket = await createSocket(opts);
 
       try {
-        const parsed = JSON.parse(value);
-        const resp = await socket.request("config", {
-          operation: "put",
-          values: { [key]: parsed },
-        });
+        const cfg = socket.config();
+        const parts = key.split("/");
+        const configEntry =
+          parts.length >= 2
+            ? { type: parts[0], key: parts.slice(1).join("/"), value }
+            : { type: "config", key, value };
+        const resp = await cfg.putConfig([configEntry]);
         console.log(JSON.stringify(resp, null, 2));
       } finally {
-        await socket.close();
+        socket.close();
       }
     });
 
   config
     .command("list")
-    .description("List configuration keys")
-    .action(async (_opts, cmd) => {
+    .description("List configuration keys for a type")
+    .argument("[type]", "Config type to list", "config")
+    .action(async (type: string, _opts, cmd) => {
       const opts = getOpts(cmd);
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request("config", { operation: "list" });
+        const cfg = socket.config();
+        const resp = await cfg.list(type);
         console.log(JSON.stringify(resp, null, 2));
       } finally {
-        await socket.close();
+        socket.close();
+      }
+    });
+
+  config
+    .command("delete")
+    .description("Delete a configuration entry")
+    .argument("<key>", "Config key (format: type/key)")
+    .action(async (key: string, _opts, cmd) => {
+      const opts = getOpts(cmd);
+      const socket = await createSocket(opts);
+
+      try {
+        const cfg = socket.config();
+        const parts = key.split("/");
+        const configKey =
+          parts.length >= 2
+            ? { type: parts[0], key: parts.slice(1).join("/") }
+            : { type: "config", key };
+        const resp = await cfg.deleteConfig(configKey);
+        console.log(JSON.stringify(resp, null, 2));
+      } finally {
+        socket.close();
       }
     });
 }

ts/packages/cli/src/commands/embeddings.ts

@@ -0,0 +1,27 @@
+/**
+ * Embeddings CLI commands.
+ *
+ * Generate text embeddings using the configured embedding model.
+ */
+
+import type { Command } from "commander";
+import { createSocket, getOpts } from "./util.js";
+
+export function registerEmbeddingsCommands(program: Command): void {
+  program
+    .command("embeddings")
+    .description("Generate text embeddings")
+    .argument("<text...>", "Text(s) to embed")
+    .action(async (texts: string[], _opts, cmd) => {
+      const opts = getOpts(cmd);
+      const socket = await createSocket(opts);
+
+      try {
+        const flow = socket.flow(opts.flow);
+        const vectors = await flow.embeddings(texts);
+        console.log(JSON.stringify(vectors, null, 2));
+      } finally {
+        socket.close();
+      }
+    });
+}

ts/packages/cli/src/commands/flow.ts

@@ -20,61 +20,73 @@ export function registerFlowCommands(program: Command): void {
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request("flow", { operation: "list" });
-        console.log(JSON.stringify(resp, null, 2));
+        const flows = socket.flows();
+        const ids = await flows.getFlows();
+        console.log(JSON.stringify(ids, null, 2));
       } finally {
-        await socket.close();
+        socket.close();
+      }
+    });
+
+  flow
+    .command("get")
+    .description("Get a flow definition")
+    .argument("<id>", "Flow ID")
+    .action(async (id: string, _opts, cmd) => {
+      const opts = getOpts(cmd);
+      const socket = await createSocket(opts);
+
+      try {
+        const flows = socket.flows();
+        const def = await flows.getFlow(id);
+        console.log(JSON.stringify(def, null, 2));
+      } finally {
+        socket.close();
       }
     });
 
   flow
     .command("start")
     .description("Start a flow")
-    .argument("<name>", "Flow name")
-    .action(async (name: string, _opts, cmd) => {
+    .argument("<id>", "Flow ID")
+    .requiredOption("-b, --blueprint <name>", "Blueprint name")
+    .option("-d, --description <text>", "Flow description", "")
+    .option("-p, --parameters <json>", "Parameters as JSON")
+    .action(async (id: string, cmdOpts, cmd) => {
       const opts = getOpts(cmd);
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request("flow", { operation: "start", name });
+        const flows = socket.flows();
+        const params = cmdOpts.parameters
+          ? JSON.parse(cmdOpts.parameters as string)
+          : undefined;
+        const resp = await flows.startFlow(
+          id,
+          cmdOpts.blueprint as string,
+          cmdOpts.description as string,
+          params as Record<string, unknown> | undefined,
+        );
         console.log(JSON.stringify(resp, null, 2));
       } finally {
-        await socket.close();
+        socket.close();
       }
     });
 
   flow
     .command("stop")
     .description("Stop a flow")
-    .argument("<name>", "Flow name")
-    .action(async (name: string, _opts, cmd) => {
+    .argument("<id>", "Flow ID")
+    .action(async (id: string, _opts, cmd) => {
       const opts = getOpts(cmd);
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request("flow", { operation: "stop", name });
+        const flows = socket.flows();
+        const resp = await flows.stopFlow(id);
         console.log(JSON.stringify(resp, null, 2));
       } finally {
-        await socket.close();
-      }
-    });
-
-  flow
-    .command("status")
-    .description("Show flow status")
-    .argument("[name]", "Flow name (all if omitted)")
-    .action(async (name: string | undefined, _opts, cmd) => {
-      const opts = getOpts(cmd);
-      const socket = await createSocket(opts);
-
-      try {
-        const resp = await socket.request("flow", {
-          operation: "status",
-          ...(name ? { name } : {}),
-        });
-        console.log(JSON.stringify(resp, null, 2));
-      } finally {
-        await socket.close();
+        socket.close();
       }
     });
 }

ts/packages/cli/src/commands/graph-rag.ts

@@ -1,5 +1,5 @@
 /**
- * Graph RAG CLI commands.
+ * Graph RAG and Document RAG CLI commands.
  *
  * Python reference: trustgraph-cli/trustgraph/cli/invoke_graph_rag.py
  */
@@ -14,24 +14,24 @@ export function registerGraphRagCommands(program: Command): void {
     .argument("<query>", "Natural language query")
     .option("--entity-limit <n>", "Max entities", "50")
     .option("--triple-limit <n>", "Max triples per entity", "30")
+    .option("--collection <name>", "Collection name")
     .action(async (query: string, cmdOpts, cmd) => {
       const opts = getOpts(cmd);
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request(
-          "graph-rag",
+        const flow = socket.flow(opts.flow);
+        const response = await flow.graphRag(
+          query,
           {
-            query,
-            entity_limit: parseInt(cmdOpts.entityLimit, 10),
-            triple_limit: parseInt(cmdOpts.tripleLimit, 10),
+            entityLimit: parseInt(cmdOpts.entityLimit, 10),
+            tripleLimit: parseInt(cmdOpts.tripleLimit, 10),
           },
-          { flowId: opts.flow },
-        ) as { response?: string };
-
-        console.log(resp.response ?? JSON.stringify(resp, null, 2));
+          cmdOpts.collection,
+        );
+        console.log(response);
       } finally {
-        await socket.close();
+        socket.close();
       }
     });
 
@@ -39,20 +39,22 @@ export function registerGraphRagCommands(program: Command): void {
     .command("document-rag")
     .description("Query documents using RAG")
     .argument("<query>", "Natural language query")
-    .action(async (query: string, _cmdOpts, cmd) => {
+    .option("--doc-limit <n>", "Max documents", "20")
+    .option("--collection <name>", "Collection name")
+    .action(async (query: string, cmdOpts, cmd) => {
       const opts = getOpts(cmd);
       const socket = await createSocket(opts);
 
       try {
-        const resp = await socket.request(
-          "document-rag",
-          { query },
-          { flowId: opts.flow },
-        ) as { response?: string };
-
-        console.log(resp.response ?? JSON.stringify(resp, null, 2));
+        const flow = socket.flow(opts.flow);
+        const response = await flow.documentRag(
+          query,
+          cmdOpts.docLimit ? parseInt(cmdOpts.docLimit, 10) : undefined,
+          cmdOpts.collection,
+        );
+        console.log(response);
       } finally {
-        await socket.close();
+        socket.close();
       }
     });
 }

ts/packages/cli/src/commands/library.ts

@@ -0,0 +1,126 @@
+/**
+ * Document library CLI commands.
+ *
+ * Manages documents stored in the TrustGraph library.
+ */
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import type { Command } from "commander";
+import { createSocket, getOpts } from "./util.js";
+
+/** Simple MIME-type lookup by file extension. */
+function guessMimeType(filepath: string): string {
+  const ext = filepath.split(".").pop()?.toLowerCase();
+  switch (ext) {
+    case "pdf":
+      return "application/pdf";
+    case "txt":
+      return "text/plain";
+    case "md":
+      return "text/markdown";
+    case "html":
+    case "htm":
+      return "text/html";
+    case "json":
+      return "application/json";
+    case "csv":
+      return "text/csv";
+    case "docx":
+      return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+export function registerLibraryCommands(program: Command): void {
+  const library = program
+    .command("library")
+    .description("Document library management");
+
+  library
+    .command("list")
+    .description("List documents in the library")
+    .action(async (_opts, cmd) => {
+      const opts = getOpts(cmd);
+      const socket = await createSocket(opts);
+
+      try {
+        const lib = socket.librarian();
+        const docs = await lib.getDocuments();
+        console.log(JSON.stringify(docs, null, 2));
+      } finally {
+        socket.close();
+      }
+    });
+
+  library
+    .command("load")
+    .description("Load a document into the library")
+    .argument("<file>", "Path to the file to load")
+    .option("-t, --title <title>", "Document title")
+    .option("-m, --mime-type <type>", "MIME type (auto-detected if omitted)")
+    .option("-c, --comments <text>", "Comments", "")
+    .option("--tags <tags...>", "Document tags")
+    .option("--id <id>", "Optional document ID")
+    .action(async (file: string, cmdOpts, cmd) => {
+      const opts = getOpts(cmd);
+      const socket = await createSocket(opts);
+
+      try {
+        const lib = socket.librarian();
+        const data = readFileSync(file);
+        const b64 = data.toString("base64");
+        const mimeType = (cmdOpts.mimeType as string | undefined) ?? guessMimeType(file);
+        const title = (cmdOpts.title as string | undefined) ?? basename(file);
+        const comments = cmdOpts.comments as string;
+        const tags: string[] = (cmdOpts.tags as string[] | undefined) ?? [];
+
+        const resp = await lib.loadDocument(
+          b64,
+          mimeType,
+          title,
+          comments,
+          tags,
+          cmdOpts.id as string | undefined,
+        );
+        console.log(JSON.stringify(resp, null, 2));
+      } finally {
+        socket.close();
+      }
+    });
+
+  library
+    .command("remove")
+    .description("Remove a document from the library")
+    .argument("<id>", "Document ID to remove")
+    .option("--collection <name>", "Collection name")
+    .action(async (id: string, cmdOpts, cmd) => {
+      const opts = getOpts(cmd);
+      const socket = await createSocket(opts);
+
+      try {
+        const lib = socket.librarian();
+        const resp = await lib.removeDocument(id, cmdOpts.collection as string | undefined);
+        console.log(JSON.stringify(resp, null, 2));
+      } finally {
+        socket.close();
+      }
+    });
+
+  library
+    .command("processing")
+    .description("List documents currently being processed")
+    .action(async (_opts, cmd) => {
+      const opts = getOpts(cmd);
+      const socket = await createSocket(opts);
+
+      try {
+        const lib = socket.librarian();
+        const items = await lib.getProcessing();
+        console.log(JSON.stringify(items, null, 2));
+      } finally {
+        socket.close();
+      }
+    });
+}

ts/packages/cli/src/commands/triples.ts

@@ -0,0 +1,48 @@
+/**
+ * Triples query CLI commands.
+ *
+ * Query the knowledge graph for subject-predicate-object triples.
+ */
+
+import type { Command } from "commander";
+import type { Term } from "@trustgraph/client";
+import { createSocket, getOpts } from "./util.js";
+
+export function registerTriplesCommands(program: Command): void {
+  program
+    .command("triples")
+    .description("Query knowledge graph triples")
+    .option("-s, --subject <iri>", "Subject IRI")
+    .option("-p, --predicate <iri>", "Predicate IRI")
+    .option("-o, --object <iri>", "Object IRI or literal")
+    .option("-l, --limit <n>", "Max results", "20")
+    .option("--collection <name>", "Collection name")
+    .action(async (cmdOpts, cmd) => {
+      const opts = getOpts(cmd);
+      const socket = await createSocket(opts);
+
+      try {
+        const flow = socket.flow(opts.flow);
+        const s: Term | undefined = cmdOpts.subject
+          ? { t: "i", i: cmdOpts.subject as string }
+          : undefined;
+        const p: Term | undefined = cmdOpts.predicate
+          ? { t: "i", i: cmdOpts.predicate as string }
+          : undefined;
+        const o: Term | undefined = cmdOpts.object
+          ? { t: "i", i: cmdOpts.object as string }
+          : undefined;
+
+        const triples = await flow.triplesQuery(
+          s,
+          p,
+          o,
+          parseInt(cmdOpts.limit as string, 10),
+          cmdOpts.collection as string | undefined,
+        );
+        console.log(JSON.stringify(triples, null, 2));
+      } finally {
+        socket.close();
+      }
+    });
+}

ts/packages/cli/src/commands/util.ts

@@ -3,10 +3,11 @@
  */
 
 import type { Command } from "commander";
-import { SocketManager } from "@trustgraph/mcp";
+import { createTrustGraphSocket, type BaseApi } from "@trustgraph/client";
 
 export interface CliOpts {
   gateway: string;
+  user: string;
   token?: string;
   flow: string;
 }
@@ -18,11 +19,36 @@ export function getOpts(cmd: Command): CliOpts {
   return root.opts() as CliOpts;
 }
 
-export async function createSocket(opts: CliOpts): Promise<SocketManager> {
-  const socket = new SocketManager({
-    gatewayUrl: opts.gateway,
-    token: opts.token,
+/**
+ * Create a BaseApi socket client and wait for the connection to be established.
+ * The client auto-connects; we listen for the first "connected/authenticated"
+ * state before handing it back to the caller.
+ */
+export async function createSocket(opts: CliOpts): Promise<BaseApi> {
+  const socket = createTrustGraphSocket(opts.user, opts.token, opts.gateway);
+
+  // Wait for the socket to reach an open state
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      unsub();
+      reject(new Error("Timed out waiting for WebSocket connection"));
+    }, 15_000);
+
+    const unsub = socket.onConnectionStateChange((state) => {
+      if (
+        state.status === "authenticated" ||
+        state.status === "unauthenticated"
+      ) {
+        clearTimeout(timeout);
+        unsub();
+        resolve();
+      } else if (state.status === "failed") {
+        clearTimeout(timeout);
+        unsub();
+        reject(new Error(state.lastError ?? "WebSocket connection failed"));
+      }
+    });
   });
-  await socket.connect();
+
   return socket;
 }

ts/packages/cli/src/index.ts

@@ -14,6 +14,9 @@ import { registerAgentCommands } from "./commands/agent.js";
 import { registerGraphRagCommands } from "./commands/graph-rag.js";
 import { registerConfigCommands } from "./commands/config.js";
 import { registerFlowCommands } from "./commands/flow.js";
+import { registerLibraryCommands } from "./commands/library.js";
+import { registerTriplesCommands } from "./commands/triples.js";
+import { registerEmbeddingsCommands } from "./commands/embeddings.js";
 
 const program = new Command();
 
@@ -22,6 +25,7 @@ program
   .description("TrustGraph CLI — interact with TrustGraph services")
   .version("0.1.0")
   .option("-g, --gateway <url>", "Gateway WebSocket URL", "ws://localhost:8088/api/v1/socket")
+  .option("-u, --user <id>", "User identifier", "cli")
   .option("-t, --token <token>", "Authentication token")
   .option("-f, --flow <id>", "Flow ID", "default");
 
@@ -29,5 +33,8 @@ registerAgentCommands(program);
 registerGraphRagCommands(program);
 registerConfigCommands(program);
 registerFlowCommands(program);
+registerLibraryCommands(program);
+registerTriplesCommands(program);
+registerEmbeddingsCommands(program);
 
 program.parse();

ts/packages/cli/tsconfig.json

@@ -2,11 +2,12 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": "src",
+    "composite": true
   },
   "include": ["src"],
   "references": [
     { "path": "../base" },
-    { "path": "../mcp" }
+    { "path": "../client" }
   ]
 }