chatbase 0.0.1 → 0.1.1

package/dist/commands/conversations/tool-result.js

@@ -0,0 +1,74 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { readTextInput } from '../../base/body-input.js';
+import { throwIfError } from '../../client/client.js';
+import { UsageError } from '../../errors/errors.js';
+export default class ConversationsToolResult extends AgentCommand {
+    static summary = 'Submit a client-side tool result to a chat turn';
+    static description = 'Submit the result of a client-side tool call so the paused chat ' +
+        'turn can continue. The tool call ID comes from the tool-call part ' +
+        'of the chat response that requested the execution.';
+    static examples = [
+        '<%= config.bin %> conversations tool-result conv_123 --tool-call-id tc_1 --output \'{"temperature": 72}\' -a agt_123',
+        '<%= config.bin %> conversations tool-result conv_123 --tool-call-id tc_1 --output @result.json -a agt_123',
+        '<%= config.bin %> conversations tool-result conv_123 --tool-call-id tc_1 -a agt_123'
+    ];
+    static args = {
+        conversationId: Args.string({
+            required: false,
+            description: 'Conversation ID (alternative to --conversation)'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        conversation: Flags.string({
+            description: 'Conversation ID'
+        }),
+        'tool-call-id': Flags.string({
+            required: true,
+            description: 'The toolCallId from the tool-call part in the chat response'
+        }),
+        output: Flags.string({
+            description: 'Result of executing the tool (inline JSON, @file, or @-); ' +
+                'a value that is not valid JSON is sent as a plain string'
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(ConversationsToolResult);
+        // Positional and flag are alternatives — `agents get <id>` set the
+        // positional convention, the flag predates it and stays supported.
+        const conversationId = args.conversationId ?? flags.conversation;
+        if (!conversationId) {
+            throw new UsageError('Missing conversation ID. Pass it positionally (`conversations tool-result <id> ...`) or via --conversation.');
+        }
+        if (args.conversationId && flags.conversation) {
+            throw new UsageError('Pass the conversation ID either positionally or via --conversation, not both.');
+        }
+        const body = {
+            toolCallId: flags['tool-call-id']
+        };
+        if (flags.output !== undefined) {
+            const raw = await readTextInput(flags.output, '--output');
+            // Tool outputs are arbitrary values in the spec: parse JSON when
+            // it is JSON, otherwise pass the text through as a string.
+            try {
+                body.output = JSON.parse(raw);
+            }
+            catch {
+                body.output = raw;
+            }
+        }
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.POST('/agents/{agentId}/conversations/{conversationId}/tool-result', {
+            params: { path: { agentId, conversationId } },
+            body
+        });
+        throwIfError(response, error);
+        if (flags.json) {
+            process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+            return;
+        }
+        this.success(flags, `Tool result submitted for ${flags['tool-call-id']}`);
+    }
+}

package/dist/commands/health.js

@@ -0,0 +1,22 @@
+import { BaseCommand } from '../base/base-command.js';
+import { throwIfError } from '../client/client.js';
+export default class Health extends BaseCommand {
+    static description = 'Check that the Chatbase API is reachable';
+    static examples = [
+        '<%= config.bin %> health',
+        '<%= config.bin %> health --json'
+    ];
+    static flags = { ...BaseCommand.baseFlags };
+    requireAuth = false;
+    async run() {
+        const { flags } = await this.parse(Health);
+        const client = this.apiClient(flags);
+        const { data, error, response } = await client.GET('/health');
+        throwIfError(response, error);
+        if (this.mode(flags) === 'json') {
+            process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+            return;
+        }
+        this.success(flags, `API is up (status: ${data?.status})`);
+    }
+}

package/dist/commands/helpdesk/statuses.js

@@ -0,0 +1,31 @@
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+const COLUMNS = [
+    { key: 'id', header: 'ID' },
+    { key: 'category', header: 'CATEGORY' },
+    { key: 'label', header: 'LABEL' }
+];
+export default class HelpdeskStatuses extends AgentCommand {
+    static description = 'List ticket statuses for an agent';
+    static examples = [
+        '<%= config.bin %> helpdesk statuses -a agt_123'
+    ];
+    static flags = { ...AgentCommand.baseFlags };
+    async run() {
+        const { flags } = await this.parse(HelpdeskStatuses);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.GET('/agents/{agentId}/helpdesk/ticket-statuses', { params: { path: { agentId } } });
+        throwIfError(response, error);
+        // TicketStatusList is a bare array, not wrapped in {data, pagination}.
+        const statuses = data;
+        const rows = statuses.map((s) => ({
+            id: String(s.id ?? ''),
+            category: String(s.category ?? ''),
+            // internalLabel is the dashboard/agent-facing label — the more
+            // relevant of the two for a CLI operator picking a statusId.
+            label: String(s.internalLabel ?? '')
+        }));
+        this.printData(flags, data, rows, COLUMNS);
+    }
+}

package/dist/commands/helpdesk/teams.js

@@ -0,0 +1,25 @@
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+const COLUMNS = [
+    { key: 'id', header: 'ID' },
+    { key: 'name', header: 'NAME' }
+];
+export default class HelpdeskTeams extends AgentCommand {
+    static description = 'List helpdesk teams for an agent';
+    static examples = ['<%= config.bin %> helpdesk teams -a agt_123'];
+    static flags = { ...AgentCommand.baseFlags };
+    async run() {
+        const { flags } = await this.parse(HelpdeskTeams);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.GET('/agents/{agentId}/helpdesk/teams', { params: { path: { agentId } } });
+        throwIfError(response, error);
+        // TeamListResponse is a bare array, not wrapped in {data, pagination}.
+        const teams = data;
+        const rows = teams.map((t) => ({
+            id: String(t.id ?? ''),
+            name: String(t.name ?? '')
+        }));
+        this.printData(flags, data, rows, COLUMNS);
+    }
+}

package/dist/commands/messages/feedback.js

@@ -0,0 +1,64 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+import { UsageError } from '../../errors/errors.js';
+export default class MessagesFeedback extends AgentCommand {
+    static description = 'Set or clear user feedback on an assistant message';
+    static examples = [
+        '<%= config.bin %> messages feedback msg_1 --conversation conv_123 --rating positive -a agt_123',
+        '<%= config.bin %> messages feedback --conversation conv_123 --message msg_1 --rating clear -a agt_123'
+    ];
+    static args = {
+        messageId: Args.string({
+            required: false,
+            description: 'Message ID (alternative to --message)'
+        })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        conversation: Flags.string({
+            required: true,
+            description: 'Conversation ID'
+        }),
+        message: Flags.string({
+            description: 'Message ID'
+        }),
+        rating: Flags.string({
+            required: true,
+            options: ['positive', 'negative', 'clear'],
+            description: 'Feedback value ("clear" removes existing feedback)'
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(MessagesFeedback);
+        // Positional and flag are alternatives — `agents get <id>` set the
+        // positional convention, the flag predates it and stays supported.
+        const messageId = args.messageId ?? flags.message;
+        if (!messageId) {
+            throw new UsageError('Missing message ID. Pass it positionally (`messages feedback <id> ...`) or via --message.');
+        }
+        if (args.messageId && flags.message) {
+            throw new UsageError('Pass the message ID either positionally or via --message, not both.');
+        }
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const feedback = flags.rating === 'positive'
+            ? 'positive'
+            : flags.rating === 'negative'
+                ? 'negative'
+                : null;
+        const body = { feedback };
+        const { error, response } = await client.PATCH('/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback', {
+            params: {
+                path: {
+                    agentId,
+                    conversationId: flags.conversation,
+                    messageId
+                }
+            },
+            body
+        });
+        throwIfError(response, error);
+        this.success(flags, `Feedback updated for message ${messageId}`);
+    }
+}

package/dist/commands/messages/list.js

@@ -0,0 +1,55 @@
+import { Flags } from '@oclif/core';
+import { ListCommand } from '../../base/list-command.js';
+import { fetchPages } from '../../client/paginate.js';
+import { formatEpochSeconds } from '../../output/render.js';
+const COLUMNS = [
+    { key: 'id', header: 'ID' },
+    { key: 'role', header: 'ROLE' },
+    { key: 'createdAt', header: 'CREATED' }
+];
+export default class MessagesList extends ListCommand {
+    static description = 'List messages in a conversation';
+    static examples = [
+        '<%= config.bin %> messages list --conversation conv_123 -a agt_123',
+        '<%= config.bin %> messages list --conversation conv_123 -a agt_123 --all --json'
+    ];
+    static flags = {
+        ...ListCommand.baseFlags,
+        conversation: Flags.string({
+            required: true,
+            description: 'Conversation ID'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(MessagesList);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { pages, items } = await fetchPages((query) => client.GET('/agents/{agentId}/conversations/{conversationId}/messages', {
+            params: {
+                path: {
+                    agentId,
+                    conversationId: flags.conversation
+                },
+                query
+            }
+        }), { limit: flags.limit, cursor: flags.cursor, all: flags.all });
+        // Humans read ISO dates; --plain keeps the raw epoch for scripts.
+        const formatTimestamp = this.mode(flags) === 'pretty'
+            ? formatEpochSeconds
+            : (v) => String(v ?? '');
+        const rows = items.map((m) => ({
+            id: String(m.id ?? ''),
+            role: String(m.role ?? ''),
+            createdAt: formatTimestamp(m.createdAt)
+        }));
+        const last = pages.at(-1);
+        // --json must stay the raw API shape even when --all merges pages
+        const raw = pages.length === 1
+            ? pages[0]
+            : { data: items, pagination: last?.pagination };
+        this.printData(flags, raw, rows, COLUMNS);
+        if (!flags.all && last?.pagination.hasMore && last.pagination.cursor) {
+            this.note(flags, `More results: rerun with --cursor ${last.pagination.cursor} (or use --all)`);
+        }
+    }
+}

package/dist/commands/sources/create.js

@@ -0,0 +1,134 @@
+import { Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { assertFileReadable } from '../../base/assert-file.js';
+import { bodyFieldFlags } from '../../base/base-command.js';
+import { readBodyData, readTextInput } from '../../base/body-input.js';
+import { throwIfError } from '../../client/client.js';
+import { filesHostMismatchWarning, uploadFileSource } from '../../client/files.js';
+import { resolveApiKey } from '../../config/resolve.js';
+import { UsageError } from '../../errors/errors.js';
+import { maybeSpinner } from '../../output/spinner.js';
+/** Merges --data (base) with per-type flags (win). Link fields default to
+ * empty/false because the API schema marks them required despite having defaults. */
+async function buildSourceBody(flags) {
+    const body = {
+        ...(await readBodyData(flags.data, flags.field)),
+        type: flags.type
+    };
+    if (flags.type === 'text') {
+        if (flags.name)
+            body.name = flags.name;
+        if (flags.content)
+            body.content = await readTextInput(flags.content);
+    }
+    else if (flags.type === 'qna') {
+        if (flags.name)
+            body.name = flags.name;
+    }
+    else if (flags.type === 'link') {
+        if (flags.url)
+            body.url = flags.url;
+        if (flags['link-type'])
+            body.linkType = flags['link-type'];
+        body.excludePaths ??= [];
+        body.includeOnlyPaths ??= [];
+        body.slowScraping ??= false;
+    }
+    return body;
+}
+export default class SourcesCreate extends AgentCommand {
+    static description = 'Create a source: text/qna/link (JSON) or a file upload';
+    static examples = [
+        '<%= config.bin %> sources create --type text --name Guide --content "hello" -a agt_123',
+        '<%= config.bin %> sources create --type link --url https://example.com --link-type crawl -a agt_123',
+        '<%= config.bin %> sources create --type qna --data \'{"questions":["Q1"],"answer":"A1"}\' -a agt_123',
+        '<%= config.bin %> sources create --file ./guide.pdf -a agt_123'
+    ];
+    static flags = {
+        ...AgentCommand.baseFlags,
+        ...bodyFieldFlags,
+        type: Flags.string({
+            options: ['text', 'qna', 'link'],
+            description: 'JSON source type (mutually exclusive with --file)',
+            exclusive: ['file']
+        }),
+        file: Flags.string({
+            description: 'Path to a file to upload as a source (mutually exclusive with --type)',
+            exclusive: ['type', 'data', 'content', 'url', 'link-type']
+        }),
+        name: Flags.string({
+            description: 'Source name (--type text/qna, or a file upload)'
+        }),
+        content: Flags.string({
+            description: 'Text content for --type text (@file, @-, or inline)'
+        }),
+        url: Flags.string({ description: 'URL for --type link' }),
+        'link-type': Flags.string({
+            options: ['individual', 'sitemap', 'crawl'],
+            description: 'Link crawl mode for --type link'
+        }),
+        data: Flags.string({
+            description: 'JSON body (@file, @-, or inline); per-type flags override matching keys'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(SourcesCreate);
+        if (!flags.type && !flags.file) {
+            throw new UsageError('Specify --type <text|qna|link> for a JSON source, or --file <path> to upload a file.');
+        }
+        // Validated before any network call, including agent-name resolution below.
+        if (flags.file)
+            assertFileReadable(flags.file);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        let id;
+        if (flags.file) {
+            const resolved = resolveApiKey();
+            if (!resolved) {
+                // Unreachable in practice: this.apiClient() above already
+                // required auth and would have thrown first.
+                throw new UsageError('Not authenticated. Run `chatbase auth login`, or set CHATBASE_API_KEY.');
+            }
+            const mismatch = filesHostMismatchWarning();
+            if (mismatch) {
+                this.note(flags, this.palette(flags).yellow(mismatch));
+            }
+            const stop = maybeSpinner(flags.quiet, `Uploading ${flags.file}…`);
+            try {
+                const uploaded = await uploadFileSource({
+                    agentId,
+                    filePath: flags.file,
+                    name: flags.name,
+                    apiKey: resolved.value,
+                    verbose: flags.verbose
+                });
+                id = uploaded.id;
+            }
+            finally {
+                stop();
+            }
+        }
+        else {
+            const body = await buildSourceBody(flags);
+            // The API requires a name for qna sources (unlike text, which
+            // defaults one) — fail fast locally instead of a server 400.
+            if (flags.type === 'qna' && !body.name) {
+                throw new UsageError('--name is required for --type qna (or include "name" in --data).');
+            }
+            const { data, error, response } = await client.POST('/agents/{agentId}/sources', {
+                params: { path: { agentId } },
+                body: body
+            });
+            throwIfError(response, error);
+            id = data.id;
+        }
+        if (flags.json) {
+            process.stdout.write(`${JSON.stringify({ id }, null, 2)}\n`);
+        }
+        else {
+            this.success(flags, `Created source ${id} (untrained)`);
+            this.note(flags, `→ chatbase sources get ${id} -a ${agentId}`);
+            process.stdout.write(`${id}\n`);
+        }
+    }
+}

package/dist/commands/sources/delete.js

@@ -0,0 +1,28 @@
+import { Args } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+export default class SourcesDelete extends AgentCommand {
+    static description = 'Delete a source (restorable via restore command)';
+    static examples = [
+        '<%= config.bin %> sources delete src_1 -a agt_1'
+    ];
+    static args = {
+        sourceId: Args.string({ required: true, description: 'Source ID' })
+    };
+    async run() {
+        const { args, flags } = await this.parse(SourcesDelete);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.DELETE('/agents/{agentId}/sources/{sourceId}', {
+            params: { path: { agentId, sourceId: args.sourceId } }
+        });
+        throwIfError(response, error);
+        this.success(flags, `Deleted source ${args.sourceId}`);
+        // Never-trained sources are hard-deleted (status "deleted") — only
+        // trained ones get the restorable "toBeDeleted" mark.
+        const status = data?.status;
+        if (status === 'toBeDeleted') {
+            this.note(flags, `↩ restore with: chatbase sources restore ${args.sourceId} -a ${agentId}`);
+        }
+    }
+}

package/dist/commands/sources/get.js

@@ -0,0 +1,35 @@
+import { Args } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { SOURCE_COLUMNS, toSourceRow } from '../../base/sources.js';
+import { throwIfError } from '../../client/client.js';
+export default class SourcesGet extends AgentCommand {
+    static description = 'Show one source';
+    static examples = [
+        '<%= config.bin %> sources get src_123 -a agt_123'
+    ];
+    static args = {
+        sourceId: Args.string({ required: true, description: 'Source ID' })
+    };
+    static flags = { ...AgentCommand.baseFlags };
+    async run() {
+        const { args, flags } = await this.parse(SourcesGet);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.GET('/agents/{agentId}/sources/{sourceId}', {
+            params: { path: { agentId, sourceId: args.sourceId } }
+        });
+        throwIfError(response, error);
+        const source = data;
+        const row = toSourceRow(source, this.mode(flags));
+        const str = (v) => (v == null ? '' : String(v));
+        this.printDetail(flags, data, row, SOURCE_COLUMNS, [
+            ['ID', row.id],
+            ['Name', row.name],
+            ['Type', row.type],
+            ['Status', row.status],
+            ['Size', row.size],
+            ['Created', str(source.createdAt)],
+            ['URL', str(source.url)]
+        ]);
+    }
+}

package/dist/commands/sources/list.js

@@ -0,0 +1,47 @@
+import { Flags } from '@oclif/core';
+import { ListCommand } from '../../base/list-command.js';
+import { SOURCE_COLUMNS, toSourceRow } from '../../base/sources.js';
+import { fetchPages } from '../../client/paginate.js';
+export default class SourcesList extends ListCommand {
+    static description = 'List sources for an agent';
+    static examples = [
+        '<%= config.bin %> sources list -a agt_123',
+        '<%= config.bin %> sources list -a agt_123 --all --json'
+    ];
+    static flags = {
+        ...ListCommand.baseFlags,
+        type: Flags.string({
+            description: 'Filter by source type'
+        }),
+        name: Flags.string({
+            description: 'Filter by source name'
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(SourcesList);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const mode = this.mode(flags);
+        const extraQuery = {};
+        if (flags.type)
+            extraQuery.type = flags.type;
+        if (flags.name)
+            extraQuery.name = flags.name;
+        const { pages, items } = await fetchPages((query) => client.GET('/agents/{agentId}/sources', {
+            params: {
+                path: { agentId },
+                query: { ...query, ...extraQuery }
+            }
+        }), { limit: flags.limit, cursor: flags.cursor, all: flags.all });
+        const rows = items.map((s) => toSourceRow(s, mode));
+        const last = pages.at(-1);
+        // --json must stay the raw API shape even when --all merges pages
+        const raw = pages.length === 1
+            ? pages[0]
+            : { data: items, pagination: last?.pagination };
+        this.printData(flags, raw, rows, SOURCE_COLUMNS);
+        if (!flags.all && last?.pagination.hasMore && last.pagination.cursor) {
+            this.note(flags, `More results: rerun with --cursor ${last.pagination.cursor} (or use --all)`);
+        }
+    }
+}

package/dist/commands/sources/restore.js

@@ -0,0 +1,22 @@
+import { Args } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+export default class SourcesRestore extends AgentCommand {
+    static description = 'Restore a deleted source';
+    static examples = [
+        '<%= config.bin %> sources restore src_1 -a agt_1'
+    ];
+    static args = {
+        sourceId: Args.string({ required: true, description: 'Source ID' })
+    };
+    async run() {
+        const { args, flags } = await this.parse(SourcesRestore);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { error, response } = await client.POST('/agents/{agentId}/sources/{sourceId}/restore', {
+            params: { path: { agentId, sourceId: args.sourceId } }
+        });
+        throwIfError(response, error);
+        this.success(flags, `Restored source ${args.sourceId}`);
+    }
+}

package/dist/commands/sources/summary.js

@@ -0,0 +1,33 @@
+import { AgentCommand } from '../../base/agent-command.js';
+import { throwIfError } from '../../client/client.js';
+const COLUMNS = [
+    { key: 'type', header: 'TYPE' },
+    { key: 'count', header: 'COUNT' },
+    { key: 'size', header: 'SIZE' }
+];
+export default class SourcesSummary extends AgentCommand {
+    static description = 'Show aggregated source counts and sizes for an agent';
+    static examples = ['<%= config.bin %> sources summary -a agt_123'];
+    static flags = { ...AgentCommand.baseFlags };
+    async run() {
+        const { flags } = await this.parse(SourcesSummary);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        const { data, error, response } = await client.GET('/agents/{agentId}/sources/summary', { params: { path: { agentId } } });
+        throwIfError(response, error);
+        const summary = data;
+        // Per-type {count, size} objects flatten to table columns; the one
+        // non-object field (shouldRetrain) reads better as a note than a row.
+        const rows = Object.entries(summary)
+            .filter((entry) => typeof entry[1] === 'object' && entry[1] !== null)
+            .map(([type, value]) => ({
+            type,
+            count: String(value.count ?? 0),
+            size: String(value.size ?? 0)
+        }));
+        this.printData(flags, data, rows, COLUMNS);
+        if (!flags.json && summary.shouldRetrain === true) {
+            this.note(flags, 'Sources changed since the last training — run `chatbase agents train` to retrain.');
+        }
+    }
+}

package/dist/commands/sources/update.js

@@ -0,0 +1,76 @@
+import { Args, Flags } from '@oclif/core';
+import { AgentCommand } from '../../base/agent-command.js';
+import { assertFileReadable } from '../../base/assert-file.js';
+import { bodyFieldFlags } from '../../base/base-command.js';
+import { readBodyData } from '../../base/body-input.js';
+import { throwIfError } from '../../client/client.js';
+import { filesHostMismatchWarning, uploadFileSource } from '../../client/files.js';
+import { resolveApiKey } from '../../config/resolve.js';
+import { UsageError } from '../../errors/errors.js';
+import { maybeSpinner } from '../../output/spinner.js';
+export default class SourcesUpdate extends AgentCommand {
+    static description = 'Update an existing source (text, qna, link, or file)';
+    static examples = [
+        '<%= config.bin %> sources update src_1 --data \'{"type":"text","content":"new"}\' -a agt_1',
+        '<%= config.bin %> sources update src_1 --file ./updated.pdf -a agt_1'
+    ];
+    static args = {
+        sourceId: Args.string({ required: true, description: 'Source ID' })
+    };
+    static flags = {
+        ...AgentCommand.baseFlags,
+        ...bodyFieldFlags,
+        data: Flags.string({
+            description: 'JSON body for text/qna/link sources (@file, @-, or inline)',
+            exclusive: ['file']
+        }),
+        file: Flags.string({
+            description: 'Path to a file to upload as a replacement (mutually exclusive with --data)',
+            exclusive: ['data', 'field']
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(SourcesUpdate);
+        if (!flags.data && !flags.file) {
+            throw new UsageError('Specify --data for JSON source updates, or --file to upload a replacement file.');
+        }
+        // Validated before any network call, including agent-name
+        // resolution below — matches the guard in sources/create.ts.
+        if (flags.file)
+            assertFileReadable(flags.file);
+        const client = this.apiClient(flags);
+        const agentId = await this.agentId(flags, client);
+        if (flags.file) {
+            const resolved = resolveApiKey();
+            if (!resolved) {
+                throw new UsageError('Not authenticated. Run `chatbase auth login`, or set CHATBASE_API_KEY.');
+            }
+            const mismatch = filesHostMismatchWarning();
+            if (mismatch) {
+                this.note(flags, this.palette(flags).yellow(mismatch));
+            }
+            const stop = maybeSpinner(flags.quiet, `Uploading ${flags.file}…`);
+            try {
+                await uploadFileSource({
+                    agentId,
+                    filePath: flags.file,
+                    sourceId: args.sourceId,
+                    apiKey: resolved.value,
+                    verbose: flags.verbose
+                });
+            }
+            finally {
+                stop();
+            }
+        }
+        else {
+            const body = await readBodyData(flags.data, flags.field);
+            const { error, response } = await client.PUT('/agents/{agentId}/sources/{sourceId}', {
+                params: { path: { agentId, sourceId: args.sourceId } },
+                body: body
+            });
+            throwIfError(response, error);
+        }
+        this.success(flags, `Updated source ${args.sourceId}`);
+    }
+}