@xano/cli 1.0.4-beta.2 → 1.0.4-beta.4

package/dist/commands/auth/index.d.ts

@@ -1,9 +1,42 @@
 import { Command } from '@oclif/core';
+export interface Instance {
+    display: string;
+    id: string;
+    name: string;
+    origin: string;
+}
+export interface AuthResult {
+    branch: null | string;
+    credentialsPath: string;
+    instance: {
+        id: string;
+        name: string;
+        origin: string;
+    };
+    profile: string;
+    user: {
+        email: string;
+        id: string;
+        name: string;
+    };
+    workspace: null | {
+        id: string;
+        name: string;
+    };
+}
+/**
+ * Match a user-supplied --instance value against the instance list:
+ * numeric values match by ID, URL/hostname values match by the instance
+ * origin's hostname, anything else matches by name. Exported for tests.
+ */
+export declare function matchInstance(instances: Instance[], query: string): Instance | undefined;
 export default class Auth extends Command {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
         branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        code: 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>;
         insecure: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -12,7 +45,9 @@ export default class Auth extends Command {
         profile: 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>;
     };
-    run(): Promise<void>;
+    run(): Promise<AuthResult>;
+    protected toErrorJson(err: unknown): unknown;
+    private acquireToken;
     private getHeaders;
     private fetchBranches;
     private fetchInstances;
@@ -22,7 +57,9 @@ export default class Auth extends Command {
     private readTokenFromStdin;
     private resolveBranch;
     private resolveInstance;
+    private resolveProfileName;
     private resolveWorkspace;
+    private resolveWorkspaceAndBranch;
     private saveProfile;
     private selectBranch;
     private selectInstance;

package/dist/commands/auth/index.js

@@ -6,9 +6,37 @@ import * as http from 'node:http';
 import { dirname } from 'node:path';
 import open from 'open';
 import { buildUserAgent, resolveCredentialsPath } from '../../base-command.js';
+function originHostname(value) {
+    try {
+        return new URL(value.includes('://') ? value : `https://${value}`).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Match a user-supplied --instance value against the instance list:
+ * numeric values match by ID, URL/hostname values match by the instance
+ * origin's hostname, anything else matches by name. Exported for tests.
+ */
+export function matchInstance(instances, query) {
+    const q = query.trim();
+    if (/^\d+$/.test(q)) {
+        return instances.find((inst) => inst.id === q);
+    }
+    if (q.includes('://') || q.includes('.')) {
+        const queryHost = originHostname(q);
+        const match = queryHost ? instances.find((inst) => originHostname(inst.origin) === queryHost) : undefined;
+        if (match) {
+            return match;
+        }
+    }
+    return instances.find((inst) => inst.name === q);
+}
 const AUTH_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 export default class Auth extends Command {
     static description = 'Authenticate with Xano via browser login';
+    static enableJsonFlag = true;
     static examples = [
         `$ xano auth
 Opening browser for Xano login...
@@ -23,10 +51,12 @@ Opening browser for Xano login at https://custom.xano.com...`,
 To authenticate, open the following URL in any browser:
   https://app.xano.com/login?dest=cli&display=code
 ? Paste the code shown in your browser: ****`,
-        `$ xano auth --no-browser --instance my-instance --workspace 5 --branch dev --profile staging
-(non-interactive: only the pasted code is prompted for)`,
+        `$ xano auth --code "$CODE" --instance https://my-instance.xano.io --workspace 5
+(fully non-interactive: no browser, no prompts; missing --branch/--profile fall back to defaults)`,
         `$ echo "$CODE" | xano auth --no-browser --instance my-instance --workspace 5 --branch dev --profile staging
 (fully scripted: the code is read from piped stdin, no prompt at all)`,
+        `$ xano auth --code "$CODE" --instance 42 --workspace 5 --json
+(machine-readable: prints the created profile as JSON)`,
     ];
     static flags = {
         branch: Flags.string({
@@ -34,6 +64,11 @@ To authenticate, open the following URL in any browser:
             description: 'Pre-select a branch by label (skips the branch picker); pass "" to skip and use the live branch',
             required: false,
         }),
+        code: Flags.string({
+            description: 'Login code copied from the browser (implies --no-browser and runs fully non-interactively). Get the code at <origin>/login?dest=cli&display=code',
+            env: 'XANO_AUTH_CODE',
+            required: false,
+        }),
         config: Flags.string({
             char: 'c',
             description: 'Path to credentials file (default: ~/.xano/credentials.yaml)',
@@ -47,7 +82,7 @@ To authenticate, open the following URL in any browser:
         }),
         instance: Flags.string({
             char: 'i',
-            description: 'Pre-select an instance by name or numeric ID (skips the instance picker)',
+            description: 'Pre-select an instance by name, numeric ID, or instance URL/hostname (skips the instance picker)',
             required: false,
         }),
         'no-browser': Flags.boolean({
@@ -76,12 +111,13 @@ To authenticate, open the following URL in any browser:
             process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
             this.warn('TLS certificate verification is disabled (insecure mode)');
         }
+        // A supplied code (flag or env), piped stdin, or --json output means no
+        // prompt can ever open: every unanswered picker falls back to its default.
+        const nonInteractive = flags.code !== undefined || (flags['no-browser'] && !process.stdin.isTTY) || this.jsonEnabled();
         try {
-            // Step 1: Get token via browser auth
+            // Step 1: Get token via supplied code or browser auth
             this.log('Starting authentication flow...');
-            const token = flags['no-browser']
-                ? await this.promptForToken(flags.origin)
-                : await this.startAuthServer(flags.origin);
+            const token = await this.acquireToken(flags.code, flags['no-browser'], flags.origin);
             // Step 2: Validate token and get user info
             this.log('');
             this.log('Validating authentication...');
@@ -110,36 +146,15 @@ To authenticate, open the following URL in any browser:
                 if (instances.length === 0) {
                     this.error('No instances found. Please check your account.');
                 }
-                instance = await this.resolveInstance(instances, flags.instance);
-            }
-            // Step 4: Workspace selection
-            let workspace;
-            let branch;
-            this.log('');
-            this.log('Fetching available workspaces...');
-            const workspaces = await this.fetchWorkspaces(token, instance.origin);
-            if (workspaces.length > 0) {
-                workspace = await this.resolveWorkspace(workspaces, flags.workspace);
-                if (workspace) {
-                    // Step 5: Branch selection
-                    this.log('');
-                    this.log('Fetching available branches...');
-                    const branches = await this.fetchBranches(token, instance.origin, workspace.id);
-                    branch = await this.resolveBranch(branches, flags.branch);
-                }
-            }
-            else if (flags.workspace) {
-                this.error(`Workspace '${flags.workspace}' not found: no workspaces are available on this instance.`);
-            }
-            if (flags.branch && !workspace) {
-                this.warn('Ignoring --branch: no workspace selected.');
+                instance = await this.resolveInstance(instances, flags.instance, nonInteractive);
             }
+            // Steps 4 + 5: Workspace and branch selection
+            const { branch, workspace } = await this.resolveWorkspaceAndBranch(token, instance.origin, flags, nonInteractive);
             // Step 6: Profile name
             this.log('');
-            // An empty --profile value means "use the default name" (same as accepting the prompt's default)
-            const profileName = flags.profile === undefined ? await this.promptProfileName() : flags.profile.trim() || 'default';
+            const profileName = await this.resolveProfileName(flags.profile, nonInteractive);
             // Step 7: Save profile
-            await this.saveProfile({
+            const credentialsPath = await this.saveProfile({
                 access_token: token,
                 account_origin: flags.origin,
                 branch,
@@ -150,6 +165,17 @@ To authenticate, open the following URL in any browser:
             }, flags.config);
             this.log('');
             this.log(`Profile '${profileName}' created successfully!`);
+            const result = {
+                branch: branch ?? null,
+                credentialsPath,
+                instance: { id: instance.id, name: instance.name, origin: instance.origin },
+                profile: profileName,
+                user: { email: user.email, id: user.id, name: user.name },
+                workspace: workspace ? { id: workspace.id, name: workspace.name } : null,
+            };
+            if (this.jsonEnabled()) {
+                this.logJson(result);
+            }
             // Ensure clean exit (the open() call can keep the event loop alive)
             process.exit(0);
         }
@@ -159,11 +185,33 @@ To authenticate, open the following URL in any browser:
             // @inquirer/core, so the thrown class won't match an imported one.
             if (error?.name === 'ExitPromptError') {
                 this.log('Authentication cancelled.');
-                return;
+                this.exit(0);
             }
             throw error;
         }
     }
+    // oclif's default toErrorJson serializes Error objects to {} (message is a
+    // non-enumerable property), leaving --json consumers with no error detail.
+    toErrorJson(err) {
+        const error = err;
+        return {
+            error: {
+                ...(error.code ? { code: error.code } : {}),
+                message: error.message ?? String(err),
+                ...(error.suggestions?.length ? { suggestions: error.suggestions } : {}),
+            },
+        };
+    }
+    async acquireToken(code, noBrowser, origin) {
+        if (code !== undefined) {
+            const token = code.trim();
+            if (token === '') {
+                this.error(`No code provided. Copy it from ${origin}/login?dest=cli&display=code and pass it via --code or XANO_AUTH_CODE.`);
+            }
+            return token;
+        }
+        return noBrowser ? this.promptForToken(origin) : this.startAuthServer(origin);
+    }
     getHeaders(accessToken) {
         return {
             'User-Agent': buildUserAgent(this.config.version),
@@ -308,7 +356,7 @@ To authenticate, open the following URL in any browser:
             process.stdin.on('error', () => resolve(data.trim()));
         });
     }
-    async resolveBranch(branches, flagValue) {
+    async resolveBranch(branches, flagValue, nonInteractive) {
         if (flagValue !== undefined) {
             // An empty value means "skip and use live branch" (same as the picker's skip option)
             if (flagValue.trim() === '') {
@@ -322,23 +370,39 @@ To authenticate, open the following URL in any browser:
             this.log(`Using branch: ${match.label}`);
             return match.id;
         }
+        if (nonInteractive) {
+            this.log('Using live branch (non-interactive; pass --branch to select one)');
+            return undefined;
+        }
         return branches.length > 1 ? this.selectBranch(branches) : undefined;
     }
-    async resolveInstance(instances, flagValue) {
+    async resolveInstance(instances, flagValue, nonInteractive) {
         if (flagValue) {
-            // Numeric values match by instance ID, anything else matches by name
-            const match = /^\d+$/.test(flagValue)
-                ? instances.find((inst) => inst.id === flagValue)
-                : instances.find((inst) => inst.name === flagValue);
+            const match = matchInstance(instances, flagValue);
             if (!match) {
-                this.error(`Instance '${flagValue}' not found. Available instances: ${instances.map((inst) => `${inst.name} (${inst.id})`).join(', ')}`);
+                this.error(`Instance '${flagValue}' not found (match by name, numeric ID, or instance URL). Available instances: ${instances.map((inst) => `${inst.name} (${inst.id})`).join(', ')}`);
             }
             this.log(`Using instance: ${match.name} (${match.display})`);
             return match;
         }
+        if (nonInteractive) {
+            if (instances.length === 1) {
+                this.log(`Using instance: ${instances[0].name} (${instances[0].display})`);
+                return instances[0];
+            }
+            this.error(`Multiple instances available; pass --instance to select one. Available instances: ${instances.map((inst) => `${inst.name} (${inst.id})`).join(', ')}`);
+        }
         return this.selectInstance(instances);
     }
-    async resolveWorkspace(workspaces, flagValue) {
+    async resolveProfileName(flagValue, nonInteractive) {
+        // An empty --profile value means "use the default name" (same as accepting the prompt's default);
+        // non-interactive runs with no --profile fall back to the default name too.
+        if (flagValue !== undefined) {
+            return flagValue.trim() || 'default';
+        }
+        return nonInteractive ? 'default' : this.promptProfileName();
+    }
+    async resolveWorkspace(workspaces, flagValue, nonInteractive) {
         if (flagValue !== undefined) {
             // An empty value means "skip workspace" (same as the picker's skip option)
             if (flagValue.trim() === '') {
@@ -352,8 +416,35 @@ To authenticate, open the following URL in any browser:
             this.log(`Using workspace: ${match.name} (${match.id})`);
             return match;
         }
+        if (nonInteractive) {
+            this.log('Skipping workspace selection (non-interactive; pass --workspace to select one)');
+            return undefined;
+        }
         return this.selectWorkspace(workspaces);
     }
+    async resolveWorkspaceAndBranch(token, instanceOrigin, flags, nonInteractive) {
+        let workspace;
+        let branch;
+        this.log('');
+        this.log('Fetching available workspaces...');
+        const workspaces = await this.fetchWorkspaces(token, instanceOrigin);
+        if (workspaces.length > 0) {
+            workspace = await this.resolveWorkspace(workspaces, flags.workspace, nonInteractive);
+            if (workspace) {
+                this.log('');
+                this.log('Fetching available branches...');
+                const branches = await this.fetchBranches(token, instanceOrigin, workspace.id);
+                branch = await this.resolveBranch(branches, flags.branch, nonInteractive);
+            }
+        }
+        else if (flags.workspace) {
+            this.error(`Workspace '${flags.workspace}' not found: no workspaces are available on this instance.`);
+        }
+        if (flags.branch && !workspace) {
+            this.warn('Ignoring --branch: no workspace selected.');
+        }
+        return { branch, workspace };
+    }
     async saveProfile(profile, configPath) {
         const credentialsPath = resolveCredentialsPath(configPath);
         const credDir = dirname(credentialsPath);
@@ -393,6 +484,7 @@ To authenticate, open the following URL in any browser:
             noRefs: true,
         });
         fs.writeFileSync(credentialsPath, yamlContent, 'utf8');
+        return credentialsPath;
     }
     async selectBranch(branches) {
         const { selectedBranch } = await inquirer.prompt([

package/dist/commands/sandbox/pull/index.js

@@ -2,6 +2,7 @@ import { Flags } from '@oclif/core';
 import snakeCase from 'lodash.snakecase';
 import BaseCommand from '../../../base-command.js';
 import { buildApiGroupFolderResolver, parseDocument } from '../../../utils/document-parser.js';
+import { fetchKnowledge, writeKnowledge } from '../../../utils/knowledge-sync.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 export default class SandboxPull extends BaseCommand {
@@ -87,7 +88,6 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
         }
         if (documents.length === 0) {
             this.log('No documents found in response');
-            return;
         }
         const outputDir = path.resolve(flags.directory);
         fs.mkdirSync(outputDir, { recursive: true });
@@ -182,7 +182,17 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
             fs.writeFileSync(filePath, doc.content, 'utf8');
             writtenCount++;
         }
-        this.log(`Pulled ${writtenCount} documents from sandbox environment to ${flags.directory}`);
+        // ── Pull knowledge ────────────────────────────────────────────────────
+        const knowledgeUrl = `${profile.instance_origin}/api:meta/sandbox/knowledge/sync`;
+        const knowledgeObjects = await fetchKnowledge(knowledgeUrl, '', profile.access_token, this.verboseFetch.bind(this), flags.verbose);
+        let knowledgeCount = 0;
+        if (knowledgeObjects.length > 0) {
+            knowledgeCount = writeKnowledge(knowledgeObjects, outputDir);
+        }
+        const parts = [`${writtenCount} documents`];
+        if (knowledgeCount > 0)
+            parts.push(`${knowledgeCount} knowledge file${knowledgeCount === 1 ? '' : 's'}`);
+        this.log(`Pulled ${parts.join(' + ')} from sandbox environment to ${flags.directory}`);
     }
     sanitizeFilename(name) {
         return snakeCase(name.replaceAll('"', ''));

package/dist/commands/sandbox/push/index.d.ts

@@ -19,6 +19,6 @@ export default class SandboxPush extends BaseCommand {
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
-    private openReview;
     private getFrontendUrl;
+    private openReview;
 }

package/dist/commands/sandbox/push/index.js

@@ -130,12 +130,29 @@ Push and open sandbox review in the browser
             branch: '',
             command: this,
             inputDir,
+            knowledge: {
+                listUrl: () => `${baseUrl}/knowledge/sync`,
+                rootDir: inputDir,
+            },
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
         if (flags.review) {
             await this.openReview(profile.instance_origin, profile.access_token, flags.verbose);
         }
     }
+    getFrontendUrl(instanceOrigin) {
+        try {
+            const url = new URL(instanceOrigin);
+            if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
+                url.port = '4200';
+                return url.origin;
+            }
+        }
+        catch {
+            // fall through
+        }
+        return instanceOrigin;
+    }
     async openReview(instanceOrigin, accessToken, verbose) {
         const response = await this.verboseFetch(`${instanceOrigin}/api:meta/sandbox/impersonate`, {
             headers: {
@@ -158,17 +175,4 @@ Push and open sandbox review in the browser
         this.log('Opening sandbox review...');
         await open(reviewUrl);
     }
-    getFrontendUrl(instanceOrigin) {
-        try {
-            const url = new URL(instanceOrigin);
-            if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
-                url.port = '4200';
-                return url.origin;
-            }
-        }
-        catch {
-            // fall through
-        }
-        return instanceOrigin;
-    }
 }

package/dist/commands/workspace/pull/index.js

@@ -4,11 +4,12 @@ import * as path from 'node:path';
 import snakeCase from 'lodash.snakecase';
 import BaseCommand from '../../../base-command.js';
 import { buildApiGroupFolderResolver, parseDocument } from '../../../utils/document-parser.js';
+import { fetchKnowledge, writeKnowledge } from '../../../utils/knowledge-sync.js';
 export default class Pull extends BaseCommand {
     static description = 'Pull a workspace multidoc from the Xano Metadata API and split into individual files';
     static examples = [
         `$ xano workspace pull
-Pulled 42 documents to current directory
+Pulled 42 documents + 5 knowledge files to current directory
 `,
         `$ xano workspace pull -d ./my-workspace
 Pulled 42 documents to ./my-workspace
@@ -239,7 +240,17 @@ Pulled 58 documents
             fs.writeFileSync(filePath, doc.content, 'utf8');
             writtenCount++;
         }
-        this.log(`Pulled ${writtenCount} documents to ${flags.directory}`);
+        // ── Pull knowledge ────────────────────────────────────────────────────
+        const knowledgeUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/knowledge/sync`;
+        const knowledgeObjects = await fetchKnowledge(knowledgeUrl, branch, profile.access_token, this.verboseFetch.bind(this), flags.verbose);
+        let knowledgeCount = 0;
+        if (knowledgeObjects.length > 0) {
+            knowledgeCount = writeKnowledge(knowledgeObjects, outputDir);
+        }
+        const parts = [`${writtenCount} documents`];
+        if (knowledgeCount > 0)
+            parts.push(`${knowledgeCount} knowledge file${knowledgeCount === 1 ? '' : 's'}`);
+        this.log(`Pulled ${parts.join(' + ')} to ${flags.directory}`);
     }
     /**
      * Sanitize a document name for use as a filename.

package/dist/commands/workspace/push/index.d.ts

@@ -4,8 +4,8 @@ export default class Push extends BaseCommand {
     static examples: string[];
     static flags: {
         branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         delete: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         env: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         exclude: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/workspace/push/index.js

@@ -53,6 +53,12 @@ Push all files except tables
 `,
         `$ xano workspace push -i "function/*" -e "**/test*"
 Push functions but exclude test files
+`,
+        `$ xano workspace push -i "knowledge/**"
+Push only knowledge files (agents.md / skills / docs)
+`,
+        `$ xano workspace push --sync --delete
+Full sync including knowledge files; removes server objects not present locally
 `,
     ];
     static flags = {
@@ -62,17 +68,17 @@ Push functions but exclude test files
             description: 'Branch name (optional if set in profile, defaults to live)',
             required: false,
         }),
+        delete: Flags.boolean({
+            default: false,
+            description: '[CRITICAL] STOP and confirm with the user before running. Delete workspace objects not included in the push (requires --sync).',
+            required: false,
+        }),
         directory: Flags.string({
             char: 'd',
             default: '.',
             description: 'Directory containing documents to push (defaults to current directory)',
             required: false,
         }),
-        delete: Flags.boolean({
-            default: false,
-            description: '[CRITICAL] STOP and confirm with the user before running. Delete workspace objects not included in the push (requires --sync).',
-            required: false,
-        }),
         'dry-run': Flags.boolean({
             default: false,
             description: 'Show preview of changes without pushing (exit after preview)',
@@ -186,6 +192,10 @@ Push functions but exclude test files
             branch,
             command: this,
             inputDir,
+            knowledge: {
+                listUrl: () => `${baseUrl}/knowledge/sync`,
+                rootDir: inputDir,
+            },
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
     }

package/dist/utils/knowledge-sync.d.ts

@@ -0,0 +1,113 @@
+export declare const KNOWLEDGE_DIR = "knowledge";
+export type KnowledgeType = 'agents.md' | 'doc' | 'skill';
+/** A reference file attached to a skill (knowledge_file). */
+export interface KnowledgeFile {
+    content: string;
+    /** Path relative to the skill's `references/` folder, POSIX-separated. */
+    name: string;
+}
+/** A workspace-scoped knowledge object as exchanged with the API. */
+export interface KnowledgeObject {
+    content: string;
+    description?: string;
+    enabled?: boolean;
+    files?: KnowledgeFile[];
+    guid?: string;
+    knowledge_type: KnowledgeType;
+    mode?: string;
+    name: string;
+    scope?: string;
+}
+/** A locally-collected object that also remembers its primary file on disk (for GUID writeback). */
+export interface LocalKnowledgeObject extends KnowledgeObject {
+    filePath: string;
+}
+export interface KnowledgePushBody {
+    branch?: string;
+    delete?: boolean;
+    dry_run?: boolean;
+    force?: boolean;
+    items: KnowledgeObject[];
+}
+export interface KnowledgePushResult {
+    deleted?: number;
+    guid_map?: Array<{
+        guid: string;
+        name: string;
+    }>;
+    imported?: number;
+    operations?: KnowledgeDryRunOperation[];
+    summary?: Record<string, KnowledgeDryRunSummary>;
+}
+export interface KnowledgeDryRunOperation {
+    action: string;
+    name: string;
+    type: string;
+}
+export interface KnowledgeDryRunSummary {
+    created: number;
+    deleted: number;
+    unchanged: number;
+    updated: number;
+}
+export interface KnowledgeDryRunResult {
+    operations: KnowledgeDryRunOperation[];
+    summary: Record<string, KnowledgeDryRunSummary>;
+}
+type VerboseFetch = (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
+/**
+ * Build a primary `.md` file body: YAML frontmatter (built from the object's
+ * structured fields) followed by the markdown content.
+ */
+export declare function buildPrimaryContent(obj: KnowledgeObject): string;
+/**
+ * Split a primary `.md` file into its frontmatter fields and markdown body.
+ * Returns `{meta: {}, body: <raw>}` when there is no leading `---` block.
+ */
+export declare function parsePrimaryContent(raw: string): {
+    body: string;
+    meta: Record<string, unknown>;
+};
+/** Read just `guid`/`name` from frontmatter (used by GUID matching). */
+export declare function parseFrontmatter(content: string): {
+    guid?: string;
+    name?: string;
+};
+/**
+ * Write knowledge objects under `<outputDir>/knowledge/`, building frontmatter
+ * and laying out skill reference files under `<skill>/references/`.
+ * Returns the number of files written (primaries + references).
+ */
+export declare function writeKnowledge(objects: KnowledgeObject[], outputDir: string): number;
+/**
+ * Walk `<inputDir>/knowledge/`, reconstructing structured knowledge objects from
+ * primary `.md` files (frontmatter → fields, body → content) and attaching each
+ * skill's `references/` files. Include/exclude globs are matched against
+ * `knowledge/<path>` (relative to inputDir), consistent with multidoc filtering.
+ * Returns `[]` when the directory is absent.
+ */
+export declare function collectKnowledgeObjects(inputDir: string, include?: string[], exclude?: string[]): LocalKnowledgeObject[];
+/** Strip the local-only `filePath` before sending objects to the API. */
+export declare function toPushItems(objects: LocalKnowledgeObject[]): KnowledgeObject[];
+/**
+ * GET workspace knowledge objects (with content). Returns `[]` on 404 (instance
+ * without the feature) or any network error, so pull degrades gracefully.
+ */
+export declare function fetchKnowledge(baseUrl: string, branch: string, accessToken: string, verboseFetch: VerboseFetch, verbose: boolean): Promise<KnowledgeObject[]>;
+/**
+ * POST knowledge objects to the workspace. Throws on non-2xx. When `body.dry_run`
+ * is set the result may carry `operations`/`summary` instead of `imported`.
+ */
+export declare function pushKnowledge(url: string, accessToken: string, verboseFetch: VerboseFetch, verbose: boolean, body: KnowledgePushBody): Promise<KnowledgePushResult>;
+/**
+ * Compute a dry-run-style preview by diffing local objects against server
+ * objects (match by `guid`, then `name`). Used when the server doesn't honor
+ * the `dry_run` flag.
+ */
+export declare function knowledgePreview(local: KnowledgeObject[], server: KnowledgeObject[], willDelete: boolean): KnowledgeDryRunResult;
+/**
+ * Set or update `guid:` in a primary `.md` file's YAML frontmatter.
+ * Returns true if the file was modified.
+ */
+export declare function syncGuidToFrontmatter(filePath: string, guid: string): boolean;
+export {};