@xano/cli 1.0.4-beta.10 → 1.0.4-beta.12

package/README.md

@@ -284,6 +284,31 @@ when the function returns an error status.
 > denied with an access error — grant run/debug to the role (or use a token whose role has
 > it). `function list`/`get`/`create`/`edit` only need the Function permission.
 
+### Knowledge
+
+```bash
+# List all enabled knowledge as markdown (always-on items show full content, on-demand show name + description)
+xano knowledge list -w 40
+
+# List as JSON
+xano knowledge list -w 40 --output json
+
+# Filter by knowledge type (skill, doc, agents.md)
+xano knowledge list -w 40 --type skill
+
+# Include disabled items
+xano knowledge list --no-enabled-only
+
+# Get a specific knowledge item's content by name
+xano knowledge get "deploy-runbook" -w 40
+
+# Get as JSON (includes all metadata)
+xano knowledge get "deploy-runbook" -w 40 --output json
+
+# Get a reference file attached to a knowledge item
+xano knowledge get "deploy-runbook" -w 40 --file checklist.md
+```
+
 ### Releases
 
 All release commands use **release names** (e.g., `v1.0`), not IDs.

package/dist/commands/knowledge/get/index.d.ts

@@ -0,0 +1,18 @@
+import BaseCommand from '../../../base-command.js';
+export default class KnowledgeGet extends BaseCommand {
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/knowledge/get/index.js

@@ -0,0 +1,126 @@
+import { Args, Flags } from '@oclif/core';
+import BaseCommand from '../../../base-command.js';
+export default class KnowledgeGet extends BaseCommand {
+    static args = {
+        name: Args.string({
+            description: 'Knowledge item name',
+            required: true,
+        }),
+    };
+    static description = 'Get a knowledge item by name, or one of its reference files';
+    static examples = [
+        '$ xano knowledge get "deploy-runbook" -w 40',
+        '$ xano knowledge get "deploy-runbook" -w 40 --output json',
+        '$ xano knowledge get "deploy-runbook" -w 40 --file checklist.md',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        branch: Flags.string({
+            char: 'b',
+            description: 'Branch ID',
+            required: false,
+        }),
+        file: Flags.string({
+            char: 'f',
+            description: 'Path of a reference file to fetch instead of the main content',
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'text',
+            description: 'Output format',
+            options: ['text', 'json'],
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(KnowledgeGet);
+        const { profile, profileName } = this.resolveProfile(flags);
+        let workspaceId;
+        if (flags.workspace) {
+            workspaceId = flags.workspace;
+        }
+        else if (profile.workspace) {
+            workspaceId = profile.workspace;
+        }
+        else {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano knowledge get <name> -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile edit ${profileName} -w <workspace_id>`);
+        }
+        const queryParams = new URLSearchParams();
+        queryParams.set('enabled_only', 'false');
+        queryParams.set('include_content', 'true');
+        if (flags.branch) {
+            queryParams.set('branch_id', flags.branch);
+        }
+        const listUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/knowledge?${queryParams.toString()}`;
+        try {
+            const listResponse = await this.verboseFetch(listUrl, {
+                headers: {
+                    'accept': 'application/json',
+                    'Authorization': `Bearer ${profile.access_token}`,
+                },
+                method: 'GET',
+            }, flags.verbose, profile.access_token);
+            if (!listResponse.ok) {
+                const errorText = await listResponse.text();
+                this.error(`API request failed with status ${listResponse.status}: ${listResponse.statusText}\n${errorText}`);
+            }
+            const data = await listResponse.json();
+            const items = Array.isArray(data) ? data : (data.items ?? []);
+            const targetName = args.name.toLowerCase();
+            const item = items.find((i) => i.name?.toLowerCase() === targetName);
+            if (!item) {
+                const available = items.map((i) => i.name).filter(Boolean).join(', ');
+                this.error(`Knowledge item not found: "${args.name}"\n` +
+                    (available ? `Available items: ${available}` : 'No knowledge items exist in this workspace.'));
+            }
+            if (flags.file) {
+                const fileParams = new URLSearchParams({ path: flags.file });
+                const fileUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/knowledge/${item.id}/file?${fileParams.toString()}`;
+                const fileResponse = await this.verboseFetch(fileUrl, {
+                    headers: {
+                        'accept': 'application/json',
+                        'Authorization': `Bearer ${profile.access_token}`,
+                    },
+                    method: 'GET',
+                }, flags.verbose, profile.access_token);
+                if (!fileResponse.ok) {
+                    const errorText = await fileResponse.text();
+                    this.error(`Failed to fetch file "${flags.file}" from knowledge item "${item.name}": ${fileResponse.status} ${fileResponse.statusText}\n${errorText}`);
+                }
+                const fileJson = await fileResponse.json();
+                const fileContent = fileJson.file?.content ?? '';
+                if (flags.output === 'json') {
+                    this.log(JSON.stringify({ content: fileContent, name: item.name, path: flags.file }, null, 2));
+                }
+                else {
+                    this.log(fileContent);
+                }
+                return;
+            }
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(item, null, 2));
+            }
+            else {
+                this.log(item.content ?? '');
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && 'oclif' in error)
+                throw error;
+            if (error instanceof Error) {
+                this.error(`Failed to fetch knowledge: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to fetch knowledge: ${String(error)}`);
+            }
+        }
+    }
+}

package/dist/commands/knowledge/list/index.d.ts

@@ -0,0 +1,18 @@
+import BaseCommand from '../../../base-command.js';
+export default class KnowledgeList extends BaseCommand {
+    static args: {};
+    static description: string;
+    static examples: string[];
+    static flags: {
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'enabled-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        type: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private formatMarkdown;
+}

package/dist/commands/knowledge/list/index.js

@@ -0,0 +1,135 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../../base-command.js';
+export default class KnowledgeList extends BaseCommand {
+    static args = {};
+    static description = 'List workspace knowledge and skills as plain-text markdown';
+    static examples = [
+        `$ xano knowledge list -w 40
+# Always-on Knowledge
+
+## deploy-runbook
+
+# Deploy Runbook
+...
+
+# On-demand Knowledge
+
+- **code-style**: Our team coding conventions
+`,
+        '$ xano knowledge list -w 40 --output json',
+        '$ xano knowledge list -w 40 --type skill',
+        '$ xano knowledge list --no-enabled-only',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        branch: Flags.string({
+            char: 'b',
+            description: 'Branch ID',
+            required: false,
+        }),
+        'enabled-only': Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Only show enabled knowledge (use --no-enabled-only to include disabled)',
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'markdown',
+            description: 'Output format',
+            options: ['markdown', 'json'],
+            required: false,
+        }),
+        type: Flags.string({
+            char: 't',
+            description: 'Filter by knowledge type',
+            options: ['skill', 'doc', 'agents.md'],
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(KnowledgeList);
+        const { profile, profileName } = this.resolveProfile(flags);
+        let workspaceId;
+        if (flags.workspace) {
+            workspaceId = flags.workspace;
+        }
+        else if (profile.workspace) {
+            workspaceId = profile.workspace;
+        }
+        else {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano knowledge list -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile edit ${profileName} -w <workspace_id>`);
+        }
+        const queryParams = new URLSearchParams();
+        queryParams.set('enabled_only', flags['enabled-only'].toString());
+        queryParams.set('include_content', 'true');
+        if (flags.branch) {
+            queryParams.set('branch_id', flags.branch);
+        }
+        if (flags.type) {
+            queryParams.set('type', flags.type);
+        }
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/knowledge?${queryParams.toString()}`;
+        try {
+            const response = await this.verboseFetch(apiUrl, {
+                headers: {
+                    'accept': 'application/json',
+                    'Authorization': `Bearer ${profile.access_token}`,
+                },
+                method: 'GET',
+            }, flags.verbose, profile.access_token);
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+            }
+            const data = await response.json();
+            const items = Array.isArray(data) ? data : (data.items ?? []);
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(items, null, 2));
+                return;
+            }
+            this.log(this.formatMarkdown(items));
+        }
+        catch (error) {
+            if (error instanceof Error && 'oclif' in error)
+                throw error;
+            if (error instanceof Error) {
+                this.error(`Failed to fetch knowledge: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to fetch knowledge: ${String(error)}`);
+            }
+        }
+    }
+    formatMarkdown(items) {
+        if (items.length === 0) {
+            return 'No knowledge items found.';
+        }
+        const alwaysOn = items.filter((item) => item.mode === 'always');
+        const onDemand = items.filter((item) => item.mode !== 'always');
+        const lines = [];
+        if (alwaysOn.length > 0) {
+            lines.push('# Always-on Knowledge');
+            for (const item of alwaysOn) {
+                lines.push('', `## ${item.name ?? '(unnamed)'}`, '', item.content ?? '', '', '---');
+            }
+        }
+        if (onDemand.length > 0) {
+            if (lines.length > 0)
+                lines.push('');
+            lines.push('# On-demand Knowledge', '');
+            for (const item of onDemand) {
+                const desc = item.description || '(no description)';
+                lines.push(`- **${item.name ?? '(unnamed)'}**: ${desc}`);
+            }
+        }
+        return lines.join('\n');
+    }
+}

package/dist/utils/knowledge-sync.js

@@ -79,6 +79,23 @@ export function parseFrontmatter(content) {
         result.name = meta.name;
     return result;
 }
+// ── Mode normalization ───────────────────────────────────────────────────────
+/**
+ * The API only accepts the backend `mode` enum (`auto` | `referenced` | `always`),
+ * but the Xano UI displays these as "On Demand" / "Manual" / "Always Included".
+ * Hand-authored frontmatter (or content copied from the UI) commonly uses the
+ * display label instead, which the API rejects with e.g. `Input "on demand" is
+ * not one of the allowable values.` (DEV-7380/DEV-7382). Normalize known aliases
+ * before every push so the backend enum value is always what's sent.
+ */
+const MODE_ALIASES = {
+    'always included': 'always',
+    'manual': 'referenced',
+    'on demand': 'auto',
+};
+function normalizeMode(mode) {
+    return MODE_ALIASES[mode.trim().toLowerCase()] ?? mode;
+}
 // ── Path mapping (CLI-owned layout) ────────────────────────────────────────────
 /**
  * Allocate a unique snake_case folder/file segment per call, suffixing
@@ -211,7 +228,7 @@ export function collectKnowledgeObjects(inputDir, include, exclude) {
             enabled: typeof meta.enabled === 'boolean' ? meta.enabled : true,
             filePath: absPath,
             knowledge_type: knowledgeType,
-            mode: typeof meta.mode === 'string' ? meta.mode : 'auto',
+            mode: typeof meta.mode === 'string' ? normalizeMode(meta.mode) : 'auto',
             name: typeof meta.name === 'string' ? meta.name : deriveName(posixPath),
             scope: typeof meta.scope === 'string' ? meta.scope : 'workspace',
         };