@agentled/cli/dist/commands/knowledge.js

CLI for Agentled — manage workflows, apps, and knowledge from the command line. Zero context-window cost for AI agents.

import { readFileSync, writeFileSync } from 'node:fs';
import { AgentledClient } from '../client.js';
import { printOutput, printError } from '../utils/output.js';
export function registerKnowledgeCommands(program) {
    const knowledge = program
        .command('knowledge')
        .alias('kg')
        .description('Access workspace knowledge base and knowledge graph');
    // --- Knowledge Data (DynamoDB lists & text) ---
    knowledge
        .command('lists')
        .description('List all knowledge lists in the workspace')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (opts) => {
        try {
            const client = new AgentledClient();
            const result = await client.listKnowledgeLists();
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('rows <listKey>')
        .description('Get rows from a knowledge list')
        .option('--limit <n>', 'Max rows to return', parseInt)
        .option('--status <status>', 'Filter rows by top-level status')
        .option('--next-token <token>', 'Pagination cursor from a previous response')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (listKey, opts) => {
        try {
            const client = new AgentledClient();
            const result = await client.getKnowledgeRows(listKey, opts.limit, opts.status, opts.nextToken);
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('rows-by-ids <rowIds...>')
        .description('Fetch specific knowledge rows by ID (max 200). Use after "kg graph edges" to resolve entity IDs.')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (rowIds, opts) => {
        try {
            const client = new AgentledClient();
            const result = await client.getKnowledgeRowsByIds(rowIds);
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('text <key>')
        .description('Get a knowledge text entry')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (key, opts) => {
        try {
            const client = new AgentledClient();
            const result = await client.getKnowledgeText(key);
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('create-list')
        .description('Create a knowledge list')
        .requiredOption('--key <key>', 'Knowledge list key')
        .requiredOption('--name <name>', 'Knowledge list name')
        .option('--fields <json>', 'JSON array of field definitions')
        .option('--list-category <value>', 'List category')
        .option('--sync-to-kg', 'Sync list rows to Knowledge Graph', false)
        .option('--entity-config <json>', 'Entity config JSON object')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (opts) => {
        try {
            const result = await new AgentledClient().createKnowledgeList({
                key: opts.key,
                name: opts.name,
                fields: opts.fields ? JSON.parse(opts.fields) : undefined,
                listCategory: opts.listCategory,
                syncToKg: opts.syncToKg,
                entityConfig: opts.entityConfig ? JSON.parse(opts.entityConfig) : undefined,
            });
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('update-list-schema')
        .description('Update a knowledge list schema')
        .requiredOption('--list-key <key>', 'Knowledge list key')
        .option('--name <name>', 'Updated name')
        .option('--add-fields <json>', 'JSON array of fields to add')
        .option('--remove-field-ids <ids...>', 'Field IDs to remove')
        .option('--sync-to-kg', 'Sync list rows to Knowledge Graph', false)
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (opts) => {
        try {
            const result = await new AgentledClient().updateKnowledgeListSchema({
                listKey: opts.listKey,
                name: opts.name,
                addFields: opts.addFields ? JSON.parse(opts.addFields) : undefined,
                removeFieldIds: opts.removeFieldIds,
                syncToKg: opts.syncToKg,
            });
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('delete-list <listKey>')
        .description('Delete a knowledge list')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (listKey, opts) => {
        try {
            const result = await new AgentledClient().deleteKnowledgeList(listKey);
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('upsert-rows')
        .description('Upsert rows into a knowledge list')
        .requiredOption('--list-key <key>', 'Knowledge list key')
        .requiredOption('--rows <json>', 'JSON array of row objects ({ rowData, id?, userKey? }) or { rows: [...] }')
        .option('--user-key <key>', 'Apply userKey to a single-row payload when row.userKey is omitted')
        .option('--merge-strategy <strategy>', 'overwrite | merge | append-arrays')
        .option('--status <status>', 'Row status')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (opts) => {
        try {
            const parsed = JSON.parse(opts.rows);
            const rows = Array.isArray(parsed) ? parsed : parsed.rows;
            if (!Array.isArray(rows) || rows.length === 0) {
                throw new Error('Rows payload must be a non-empty JSON array or { rows: [...] }');
            }
            if (opts.userKey && rows.length > 1) {
                throw new Error('When using --user-key, provide exactly one row. For multi-row payloads, set userKey per row.');
            }
            const normalizedRows = rows.map((row, index) => ({
                ...row,
                userKey: row.userKey ?? (opts.userKey && index === 0 ? opts.userKey : undefined),
            }));
            const result = await new AgentledClient().upsertKnowledgeRows({
                listKey: opts.listKey,
                rows: normalizedRows,
                mergeStrategy: opts.mergeStrategy,
                status: opts.status,
            });
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('delete-rows')
        .description('Delete rows from a knowledge list')
        .requiredOption('--list-key <key>', 'Knowledge list key')
        .requiredOption('--row-ids <ids...>', 'One or more row IDs to delete')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (opts) => {
        try {
            const result = await new AgentledClient().deleteKnowledgeRows({
                listKey: opts.listKey,
                rowIds: opts.rowIds,
                confirm: true,
            });
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('upsert-text')
        .description('Create or update a knowledge text entry')
        .requiredOption('--key <key>', 'Knowledge text key')
        .requiredOption('--content <content>', 'Text content')
        .option('--title <title>', 'Optional title')
        .option('--tags <tags...>', 'Optional tags')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (opts) => {
        try {
            const result = await new AgentledClient().upsertKnowledgeText({
                key: opts.key,
                content: opts.content,
                title: opts.title,
                tags: opts.tags,
            });
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('delete-text <key>')
        .description('Delete a knowledge text entry')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (key, opts) => {
        try {
            const result = await new AgentledClient().deleteKnowledgeText(key);
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('snapshot <listKey>')
        .description('Capture a full point-in-time backup of a knowledge list. Writes JSON to --out file or stdout.')
        .option('--out <file>', 'Write snapshot JSON to this file instead of stdout')
        .option('--format <fmt>', 'Output format (when writing to stdout)', 'json')
        .action(async (listKey, opts) => {
        try {
            const result = await new AgentledClient().snapshotKnowledgeList({ listKey });
            if (opts.out) {
                writeFileSync(opts.out, JSON.stringify(result, null, 2));
                console.log(`Snapshot written to ${opts.out} (${result.rowCount ?? '?'} rows)`);
            }
            else {
                printOutput(result, opts.format);
            }
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    knowledge
        .command('restore <listKey>')
        .description('Restore a knowledge list from a snapshot file. Never wipes computed fields.')
        .requiredOption('--from <file>', 'Path to snapshot JSON file (from "kg snapshot")')
        .option('--mode <mode>', '"merge-restore" (default) shallow-merges snapshot fields into existing rows; "append" inserts only missing rows', 'merge-restore')
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (listKey, opts) => {
        try {
            let snapshotData;
            try {
                snapshotData = JSON.parse(readFileSync(opts.from, 'utf8'));
            }
            catch {
                throw new Error(`Could not read snapshot file: ${opts.from}`);
            }
            if (!['merge-restore', 'append'].includes(opts.mode)) {
                throw new Error('--mode must be "merge-restore" or "append"');
            }
            const result = await new AgentledClient().restoreKnowledgeListSnapshot({
                listKey,
                snapshotData,
                mode: opts.mode,
            });
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    // --- Knowledge Graph (Graphiti) ---
    const graph = knowledge
        .command('graph')
        .description('Query the Knowledge Graph (entities, edges, scoring)');
    graph
        .command('edges')
        .description('Traverse Knowledge Graph edges by entity name and/or relationship type')
        .option('--entity <name>', 'Filter by entity name')
        .option('--relation <type>', 'Filter by relationship type (e.g. INVESTED_IN, CO_INVESTED_WITH, SCORED)')
        .option('--limit <n>', 'Max edges to return (default 100, max 500)', parseInt)
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (opts) => {
        try {
            const client = new AgentledClient();
            const result = await client.traverseEdges({
                entityName: opts.entity,
                relationshipType: opts.relation,
                limit: opts.limit,
            });
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
    graph
        .command('scoring')
        .description('Fetch scoring history from the Knowledge Graph')
        .option('--entity <name>', 'Filter by entity name')
        .option('--limit <n>', 'Max records to return', parseInt)
        .option('--format <fmt>', 'Output format', 'json')
        .action(async (opts) => {
        try {
            const client = new AgentledClient();
            const result = await client.getScoringHistory({
                entityName: opts.entity,
                limit: opts.limit,
            });
            printOutput(result, opts.format);
        }
        catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            printError(message);
        }
    });
}
//# sourceMappingURL=knowledge.js.map