@xano/cli 0.0.94 → 0.0.95-beta.10

package/dist/commands/tenant/workflow_test/run/index.js

@@ -0,0 +1,126 @@
+import { Args, Flags } from '@oclif/core';
+import BaseCommand from '../../../../base-command.js';
+export default class TenantWorkflowTestRun extends BaseCommand {
+    static args = {
+        workflow_test_id: Args.integer({
+            description: 'ID of the workflow test to run',
+            required: true,
+        }),
+    };
+    static description = 'Run a workflow test for a tenant';
+    static examples = [
+        `$ xano tenant workflow-test run 42 -t my-tenant
+Running workflow test 42...
+Result: PASS (0.25s)
+`,
+        `$ xano tenant workflow-test run 42 -t my-tenant -o json`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        tenant: Flags.string({
+            char: 't',
+            description: 'Tenant name',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (uses profile workspace if not provided)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(TenantWorkflowTestRun);
+        const profileName = flags.profile || this.getDefaultProfile();
+        const credentials = this.loadCredentialsFile();
+        if (!credentials || !(profileName in credentials.profiles)) {
+            this.error(`Profile '${profileName}' not found.\nCreate a profile using 'xano profile create'`);
+        }
+        const profile = credentials.profiles[profileName];
+        if (!profile.instance_origin) {
+            this.error(`Profile '${profileName}' is missing instance_origin`);
+        }
+        if (!profile.access_token) {
+            this.error(`Profile '${profileName}' is missing access_token`);
+        }
+        const workspaceId = flags.workspace || profile.workspace;
+        if (!workspaceId) {
+            this.error('No workspace ID provided. Use --workspace flag or set one in your profile.');
+        }
+        // Resolve tenant to get its workspace
+        const tenantUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${encodeURIComponent(flags.tenant)}`;
+        let tenantWorkspaceId;
+        try {
+            const tenantResponse = await this.verboseFetch(tenantUrl, {
+                headers: {
+                    accept: 'application/json',
+                    Authorization: `Bearer ${profile.access_token}`,
+                },
+                method: 'GET',
+            }, flags.verbose, profile.access_token);
+            if (!tenantResponse.ok) {
+                const errorText = await tenantResponse.text();
+                this.error(`Failed to find tenant '${flags.tenant}': ${tenantResponse.status}\n${errorText}`);
+            }
+            const tenant = (await tenantResponse.json());
+            tenantWorkspaceId = String(tenant.workspace?.id || workspaceId);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to resolve tenant: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to resolve tenant: ${String(error)}`);
+            }
+        }
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${tenantWorkspaceId}/workflow_test/${args.workflow_test_id}/run`;
+        try {
+            if (flags.output === 'summary') {
+                this.log(`Running workflow test ${args.workflow_test_id}...`);
+            }
+            const response = await this.verboseFetch(apiUrl, {
+                headers: {
+                    accept: 'application/json',
+                    Authorization: `Bearer ${profile.access_token}`,
+                    'Content-Type': 'application/json',
+                },
+                method: 'POST',
+            }, 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 result = (await response.json());
+            if (flags.output === 'json') {
+                this.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                const timing = result.timing ? ` (${result.timing}s)` : '';
+                if (result.status === 'ok') {
+                    this.log(`Result: PASS${timing}`);
+                }
+                else {
+                    this.log(`Result: FAIL${timing}`);
+                    if (result.message) {
+                        this.log(`  Error: ${result.message}`);
+                    }
+                    this.exit(1);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to run workflow test: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to run workflow test: ${String(error)}`);
+            }
+        }
+    }
+}

package/dist/commands/tenant/workflow_test/run_all/index.d.ts

@@ -0,0 +1,14 @@
+import BaseCommand from '../../../../base-command.js';
+export default class TenantWorkflowTestRunAll extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        tenant: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        workspace: 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/tenant/workflow_test/run_all/index.js

@@ -0,0 +1,201 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../../../base-command.js';
+export default class TenantWorkflowTestRunAll extends BaseCommand {
+    static description = 'Run all workflow tests for a tenant';
+    static examples = [
+        `$ xano tenant workflow-test run-all -t my-tenant
+Running 3 workflow tests...
+
+PASS  my-test (0.25s)
+FAIL  data-check (0.10s)
+      Error: assertion failed
+
+Results: 2 passed, 1 failed
+`,
+        `$ xano tenant workflow-test run-all -t my-tenant -o json`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        branch: Flags.string({
+            char: 'b',
+            description: 'Filter by branch name',
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'summary',
+            description: 'Output format',
+            options: ['summary', 'json'],
+            required: false,
+        }),
+        tenant: Flags.string({
+            char: 't',
+            description: 'Tenant name',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (uses profile workspace if not provided)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(TenantWorkflowTestRunAll);
+        const profileName = flags.profile || this.getDefaultProfile();
+        const credentials = this.loadCredentialsFile();
+        if (!credentials || !(profileName in credentials.profiles)) {
+            this.error(`Profile '${profileName}' not found.\nCreate a profile using 'xano profile create'`);
+        }
+        const profile = credentials.profiles[profileName];
+        if (!profile.instance_origin) {
+            this.error(`Profile '${profileName}' is missing instance_origin`);
+        }
+        if (!profile.access_token) {
+            this.error(`Profile '${profileName}' is missing access_token`);
+        }
+        const workspaceId = flags.workspace || profile.workspace;
+        if (!workspaceId) {
+            this.error('No workspace ID provided. Use --workspace flag or set one in your profile.');
+        }
+        // Resolve tenant to get its workspace
+        const tenantUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${encodeURIComponent(flags.tenant)}`;
+        let tenantWorkspaceId;
+        try {
+            const tenantResponse = await this.verboseFetch(tenantUrl, {
+                headers: {
+                    accept: 'application/json',
+                    Authorization: `Bearer ${profile.access_token}`,
+                },
+                method: 'GET',
+            }, flags.verbose, profile.access_token);
+            if (!tenantResponse.ok) {
+                const errorText = await tenantResponse.text();
+                this.error(`Failed to find tenant '${flags.tenant}': ${tenantResponse.status}\n${errorText}`);
+            }
+            const tenant = (await tenantResponse.json());
+            tenantWorkspaceId = String(tenant.workspace?.id || workspaceId);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to resolve tenant: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to resolve tenant: ${String(error)}`);
+            }
+        }
+        const baseUrl = `${profile.instance_origin}/api:meta/workspace/${tenantWorkspaceId}/workflow_test`;
+        try {
+            const listParams = new URLSearchParams();
+            listParams.set('per_page', '10000');
+            if (flags.branch)
+                listParams.set('branch', flags.branch);
+            const listResponse = await this.verboseFetch(`${baseUrl}?${listParams}`, {
+                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(`Failed to list workflow tests: ${listResponse.status}: ${listResponse.statusText}\n${errorText}`);
+            }
+            const data = (await listResponse.json());
+            let tests;
+            if (Array.isArray(data)) {
+                tests = data;
+            }
+            else if (data && typeof data === 'object' && 'items' in data && Array.isArray(data.items)) {
+                tests = data.items;
+            }
+            else {
+                this.error('Unexpected API response format');
+            }
+            if (tests.length === 0) {
+                this.log('No workflow tests found');
+                return;
+            }
+            if (flags.output === 'summary') {
+                this.log(`Running ${tests.length} workflow test${tests.length === 1 ? '' : 's'}...\n`);
+            }
+            const results = [];
+            for (const test of tests) {
+                const runUrl = `${baseUrl}/${test.id}/run`;
+                try {
+                    const runResponse = await this.verboseFetch(runUrl, {
+                        headers: {
+                            accept: 'application/json',
+                            Authorization: `Bearer ${profile.access_token}`,
+                            'Content-Type': 'application/json',
+                        },
+                        method: 'POST',
+                    }, flags.verbose, profile.access_token);
+                    if (!runResponse.ok) {
+                        const errorText = await runResponse.text();
+                        results.push({
+                            message: `API error ${runResponse.status}: ${errorText}`,
+                            name: test.name,
+                            status: 'fail',
+                        });
+                        if (flags.output === 'summary') {
+                            this.log(`FAIL  ${test.name}`);
+                            this.log(`      Error: API error ${runResponse.status}`);
+                        }
+                        continue;
+                    }
+                    const runResult = (await runResponse.json());
+                    const passed = runResult.status === 'ok';
+                    results.push({
+                        message: runResult.message,
+                        name: test.name,
+                        status: passed ? 'pass' : 'fail',
+                        timing: runResult.timing,
+                    });
+                    if (flags.output === 'summary') {
+                        const timing = runResult.timing ? ` (${runResult.timing}s)` : '';
+                        if (passed) {
+                            this.log(`PASS  ${test.name}${timing}`);
+                        }
+                        else {
+                            this.log(`FAIL  ${test.name}${timing}`);
+                            if (runResult.message) {
+                                this.log(`      Error: ${runResult.message}`);
+                            }
+                        }
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    results.push({
+                        message,
+                        name: test.name,
+                        status: 'fail',
+                    });
+                    if (flags.output === 'summary') {
+                        this.log(`FAIL  ${test.name}`);
+                        this.log(`      Error: ${message}`);
+                    }
+                }
+            }
+            const passed = results.filter((r) => r.status === 'pass').length;
+            const failed = results.filter((r) => r.status === 'fail').length;
+            if (flags.output === 'json') {
+                this.log(JSON.stringify({ failed, passed, results }, null, 2));
+            }
+            else {
+                this.log(`\nResults: ${passed} passed, ${failed} failed`);
+            }
+            if (failed > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to run workflow tests: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to run workflow tests: ${String(error)}`);
+            }
+        }
+    }
+}

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

@@ -9,6 +9,7 @@ export default class WorkspaceEdit extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        'allow-push': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;

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

@@ -35,6 +35,11 @@ Updated workspace: my-workspace (ID: 123)
     ];
     static flags = {
         ...BaseCommand.baseFlags,
+        'allow-push': Flags.boolean({
+            allowNo: true,
+            description: 'Enable or disable direct CLI push to this workspace (not applicable on Free plan)',
+            required: false,
+        }),
         description: Flags.string({
             char: 'd',
             description: 'New description for the workspace',
@@ -102,9 +107,12 @@ Updated workspace: my-workspace (ID: 123)
         if (flags['require-token'] !== undefined) {
             body.documentation = { require_token: flags['require-token'] };
         }
+        if (flags['allow-push'] !== undefined) {
+            body.preferences = { allow_push: flags['allow-push'] };
+        }
         // Check if at least one field is being updated
         if (Object.keys(body).length === 0) {
-            this.error('No fields specified to update. Use --name, --description, --swagger, or --require-token flags.\n' +
+            this.error('No fields specified to update. Use --name, --description, --swagger, --require-token, or --allow-push flags.\n' +
                 'Example: xano workspace edit 123 --name "new-name"');
         }
         // Construct the API URL
@@ -114,8 +122,8 @@ Updated workspace: my-workspace (ID: 123)
             const response = await this.verboseFetch(apiUrl, {
                 body: JSON.stringify(body),
                 headers: {
-                    'accept': 'application/json',
-                    'Authorization': `Bearer ${profile.access_token}`,
+                    accept: 'application/json',
+                    Authorization: `Bearer ${profile.access_token}`,
                     'Content-Type': 'application/json',
                 },
                 method: 'PUT',
@@ -124,7 +132,7 @@ Updated workspace: my-workspace (ID: 123)
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
-            const workspace = await response.json();
+            const workspace = (await response.json());
             // Output results
             if (flags.output === 'json') {
                 this.log(JSON.stringify(workspace, null, 2));
@@ -141,6 +149,9 @@ Updated workspace: my-workspace (ID: 123)
                 if (workspace.documentation?.require_token !== undefined) {
                     this.log(`  Require Token: ${workspace.documentation.require_token}`);
                 }
+                if (workspace.preferences?.allow_push !== undefined) {
+                    this.log(`  Allow Push: ${workspace.preferences.allow_push}`);
+                }
             }
         }
         catch (error) {
@@ -157,8 +168,7 @@ Updated workspace: my-workspace (ID: 123)
         const credentialsPath = path.join(configDir, 'credentials.yaml');
         // Check if credentials file exists
         if (!fs.existsSync(credentialsPath)) {
-            this.error(`Credentials file not found at ${credentialsPath}\n` +
-                `Create a profile using 'xano profile create'`);
+            this.error(`Credentials file not found at ${credentialsPath}\n` + `Create a profile using 'xano profile create'`);
         }
         // Read credentials file
         try {

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

@@ -73,8 +73,8 @@ Workspace: my-workspace (ID: 123)
         try {
             const response = await this.verboseFetch(apiUrl, {
                 headers: {
-                    'accept': 'application/json',
-                    'Authorization': `Bearer ${profile.access_token}`,
+                    accept: 'application/json',
+                    Authorization: `Bearer ${profile.access_token}`,
                 },
                 method: 'GET',
             }, flags.verbose, profile.access_token);
@@ -82,7 +82,7 @@ Workspace: my-workspace (ID: 123)
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
-            const workspace = await response.json();
+            const workspace = (await response.json());
             // Output results
             if (flags.output === 'json') {
                 this.log(JSON.stringify(workspace, null, 2));
@@ -94,13 +94,16 @@ Workspace: my-workspace (ID: 123)
                     this.log(`  Description: ${workspace.description}`);
                 }
                 if (workspace.created_at) {
-                    const createdDate = new Date(workspace.created_at * 1000).toISOString().split('T')[0];
+                    const createdDate = new Date(workspace.created_at).toISOString().split('T')[0];
                     this.log(`  Created: ${createdDate}`);
                 }
                 if (workspace.updated_at) {
-                    const updatedDate = new Date(workspace.updated_at * 1000).toISOString().split('T')[0];
+                    const updatedDate = new Date(workspace.updated_at).toISOString().split('T')[0];
                     this.log(`  Updated: ${updatedDate}`);
                 }
+                if (workspace.preferences?.allow_push !== undefined) {
+                    this.log(`  Allow Push: ${workspace.preferences.allow_push}`);
+                }
             }
         }
         catch (error) {
@@ -117,8 +120,7 @@ Workspace: my-workspace (ID: 123)
         const credentialsPath = path.join(configDir, 'credentials.yaml');
         // Check if credentials file exists
         if (!fs.existsSync(credentialsPath)) {
-            this.error(`Credentials file not found at ${credentialsPath}\n` +
-                `Create a profile using 'xano profile create'`);
+            this.error(`Credentials file not found at ${credentialsPath}\n` + `Create a profile using 'xano profile create'`);
         }
         // Read credentials file
         try {

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

@@ -3,6 +3,7 @@ export default class WorkspaceList extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        latest: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         output: import("@oclif/core/interfaces").OptionFlag<string, 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>;

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

@@ -45,6 +45,10 @@ Available workspaces:
     ];
     static flags = {
         ...BaseCommand.baseFlags,
+        latest: Flags.boolean({
+            default: false,
+            description: 'Sort by newest first (descending ID)',
+        }),
         output: Flags.string({
             char: 'o',
             default: 'summary',
@@ -78,8 +82,8 @@ Available workspaces:
         try {
             const response = await this.verboseFetch(apiUrl, {
                 headers: {
-                    'accept': 'application/json',
-                    'Authorization': `Bearer ${profile.access_token}`,
+                    accept: 'application/json',
+                    Authorization: `Bearer ${profile.access_token}`,
                 },
                 method: 'GET',
             }, flags.verbose, profile.access_token);
@@ -87,7 +91,7 @@ Available workspaces:
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
-            const data = await response.json();
+            const data = (await response.json());
             // Handle different response formats
             let workspaces;
             if (Array.isArray(data)) {
@@ -99,6 +103,9 @@ Available workspaces:
             else {
                 this.error('Unexpected API response format');
             }
+            if (flags.latest) {
+                workspaces.sort((a, b) => b.id - a.id);
+            }
             // Output results
             if (flags.output === 'json') {
                 this.log(JSON.stringify(workspaces, null, 2));
@@ -111,11 +118,12 @@ Available workspaces:
                 else {
                     this.log('Available workspaces:');
                     for (const workspace of workspaces) {
+                        const created = workspace.created_at ? ` (created: ${workspace.created_at.split(' ')[0]})` : '';
                         if (workspace.id === undefined) {
-                            this.log(`  - ${workspace.name}`);
+                            this.log(`  - ${workspace.name}${created}`);
                         }
                         else {
-                            this.log(`  - ${workspace.name} (ID: ${workspace.id})`);
+                            this.log(`  - ${workspace.name} (ID: ${workspace.id})${created}`);
                         }
                     }
                 }
@@ -135,8 +143,7 @@ Available workspaces:
         const credentialsPath = path.join(configDir, 'credentials.yaml');
         // Check if credentials file exists
         if (!fs.existsSync(credentialsPath)) {
-            this.error(`Credentials file not found at ${credentialsPath}\n` +
-                `Create a profile using 'xano profile:create'`);
+            this.error(`Credentials file not found at ${credentialsPath}\n` + `Create a profile using 'xano profile:create'`);
         }
         // Read credentials file
         try {

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

@@ -282,6 +282,25 @@ Push functions but exclude test files
                     }
                     else {
                         const errorText = await dryRunResponse.text();
+                        // Check if push is disabled on this workspace
+                        try {
+                            const errorJson = JSON.parse(errorText);
+                            if (errorJson.message?.includes('Push is disabled')) {
+                                this.log('');
+                                this.log(ux.colorize('red', ux.colorize('bold', 'Direct push to this workspace is disabled.')));
+                                this.log(ux.colorize('dim', 'To apply changes to the workspace, use the sandbox review flow:'));
+                                this.log(`  ${ux.colorize('cyan', 'xano sandbox push')}    ${ux.colorize('dim', '— push changes to your sandbox')}`);
+                                this.log(`  ${ux.colorize('cyan', 'xano sandbox review')}  ${ux.colorize('dim', '— edit any logic, inspect the snapshot diff, and promote changes to the workspace')}`);
+                                this.log('');
+                                this.log(ux.colorize('dim', 'To enable direct push, go to Workspace Settings → CLI → Allow Direct Workspace Push.'));
+                                this.log(ux.colorize('dim', 'Note: This setting does not apply to Free plan instances.'));
+                                this.log('');
+                                return;
+                            }
+                        }
+                        catch {
+                            // Not JSON, fall through
+                        }
                         this.warn(`Push preview failed (${dryRunResponse.status}). Skipping preview.`);
                         if (flags.verbose) {
                             this.log(ux.colorize('dim', errorText));
@@ -465,6 +484,15 @@ Push functions but exclude test files
                     if (errorJson.payload?.param) {
                         errorMessage += `\n  Parameter: ${errorJson.payload.param}`;
                     }
+                    // Provide clear guidance when push is disabled
+                    if (errorJson.message?.includes('Push is disabled')) {
+                        this.error(`Push is disabled for this workspace.\n\n` +
+                            `To enable, go to Workspace Settings and turn on "Allow Push".\n` +
+                            `Note: This setting does not apply to Free plan instances.\n\n` +
+                            `Alternatively, use sandbox commands:\n` +
+                            `  xano sandbox push ${args.directory}\n` +
+                            `  xano sandbox impersonate`);
+                    }
                 }
                 catch {
                     errorMessage += `\n${errorText}`;
@@ -635,7 +663,7 @@ Push functions but exclude test files
                 const color = op.action === 'update' || op.action === 'update_field' ? 'yellow' : 'green';
                 const actionLabel = op.action.toUpperCase();
                 this.log(`  ${ux.colorize(color, actionLabel.padEnd(16))} ${op.type.padEnd(18)} ${op.name}`);
-                if (op.details) {
+                if (verbose && op.details) {
                     this.log(`  ${' '.repeat(16)} ${' '.repeat(18)} ${ux.colorize('dim', op.details)}`);
                 }
                 if (verbose && op.reason) {
@@ -656,7 +684,7 @@ Push functions but exclude test files
                 const color = op.action === 'truncate' || op.action === 'alter_field' ? 'yellow' : 'red';
                 const actionLabel = op.action.toUpperCase();
                 this.log(`  ${ux.colorize(color, actionLabel.padEnd(16))} ${op.type.padEnd(18)} ${op.name}`);
-                if (op.details) {
+                if (verbose && op.details) {
                     this.log(`  ${' '.repeat(16)} ${' '.repeat(18)} ${ux.colorize('dim', op.details)}`);
                 }
                 if (verbose && op.reason) {

package/dist/help.d.ts

@@ -12,9 +12,10 @@ declare class CustomCommandHelp extends BaseCommandHelp {
     protected flagHelpLabel(flag: Command.Flag.Any, showOptions?: boolean): string;
 }
 /**
- * Custom Help class that uses CustomCommandHelp
+ * Custom Help class that injects promoted commands into the COMMANDS list
  */
 export default class Help extends BaseHelp {
     protected CommandHelpClass: typeof CustomCommandHelp;
+    formatCommands(commands: Command.Loadable[]): string;
 }
 export {};

package/dist/help.js

@@ -1,5 +1,15 @@
 import { Help as BaseHelp } from '@oclif/core';
 import { CommandHelp as BaseCommandHelp } from '@oclif/core/help';
+/**
+ * Extra commands to include in the top-level COMMANDS list.
+ * These are nested commands promoted for discoverability.
+ */
+const PROMOTED_COMMANDS = [
+    { description: 'Create a new workspace', label: 'workspace create' },
+    { description: 'List workspaces', label: 'workspace list' },
+    { description: 'Pull a workspace to local files', label: 'workspace pull' },
+    { description: 'Push local documents to a workspace', label: 'workspace push' },
+];
 /**
  * Custom CommandHelp class that extends the default to display environment variables
  * alongside flag descriptions
@@ -19,8 +29,36 @@ class CustomCommandHelp extends BaseCommandHelp {
     }
 }
 /**
- * Custom Help class that uses CustomCommandHelp
+ * Custom Help class that injects promoted commands into the COMMANDS list
  */
 export default class Help extends BaseHelp {
     CommandHelpClass = CustomCommandHelp;
+    formatCommands(commands) {
+        if (commands.length === 0 && PROMOTED_COMMANDS.length === 0)
+            return '';
+        // Check before IDs are mutated: root help has top-level commands (no colons)
+        const isRootHelp = commands.some((c) => !c.id.includes(':'));
+        const entries = commands
+            .filter((c) => (this.opts.hideAliasesFromRoot ? !c.aliases?.includes(c.id) : true))
+            .filter((c) => c.id !== 'plugins')
+            .map((c) => {
+            if (this.config.topicSeparator !== ':')
+                c.id = c.id.replaceAll(':', this.config.topicSeparator);
+            const summary = this.summary(c);
+            return [c.id, summary ? summary.replace(/\u001B\[\d+m/g, '') : ''];
+        });
+        // Only add promoted commands at the root level, not within a specific topic
+        if (isRootHelp) {
+            for (const promoted of PROMOTED_COMMANDS) {
+                entries.push([promoted.label, promoted.description]);
+            }
+        }
+        entries.sort((a, b) => a[0].localeCompare(b[0]));
+        const body = this.renderList(entries, {
+            indentation: 2,
+            spacer: '\n',
+            stripAnsi: this.opts.stripAnsi,
+        });
+        return this.section('COMMANDS', body + `\n\n\x1b[2mSee xano <topic> --help for all commands in a topic.\x1b[0m`);
+    }
 }