@capawesome/cli 4.11.0 → 4.12.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [4.12.0](https://github.com/capawesome-team/cli/compare/v4.11.0...v4.12.0) (2026-06-08)
+
+
+### Features
+
+* add AI-powered failure summary for builds and deployments ([#167](https://github.com/capawesome-team/cli/issues/167)) ([ff87668](https://github.com/capawesome-team/cli/commit/ff876683036f884cbe453bc6c00fe964d035f57c))
+* **environments:** add `get` command and `--name` option to `set`/`unset` ([#168](https://github.com/capawesome-team/cli/issues/168)) ([64fe273](https://github.com/capawesome-team/cli/commit/64fe273b2db3533f7d7929c6db4806720f1d9e50))
+* **liveupdates:** support Cordova app type in `generate-signing-key` ([#166](https://github.com/capawesome-team/cli/issues/166)) ([ea81c0f](https://github.com/capawesome-team/cli/commit/ea81c0fc86d89f1c81a18b3c59e9f642eee03f07))
+
 ## [4.11.0](https://github.com/capawesome-team/cli/compare/v4.10.0...v4.11.0) (2026-06-02)
 
 

package/dist/commands/apps/builds/create.js

@@ -8,6 +8,7 @@ import { parseKeyValuePairs } from '../../../utils/app-environments.js';
 import { withAuth } from '../../../utils/auth.js';
 import { createBufferFromPath } from '../../../utils/buffer.js';
 import { isInteractive } from '../../../utils/environment.js';
+import { offerJobFailureSummary } from '../../../utils/job-failure-summary.js';
 import { isDirectory, isReadable } from '../../../utils/file.js';
 import { waitForJobCompletion } from '../../../utils/job.js';
 import { prompt, promptAppSelection, promptOrganizationSelection } from '../../../utils/prompt.js';
@@ -44,6 +45,10 @@ export default defineCommand({
             .optional()
             .describe('Exit immediately after creating the build without waiting for completion.'),
         environment: z.string().optional().describe('The name of the environment to use for the build.'),
+        failureSummary: z
+            .boolean()
+            .optional()
+            .describe('Request an AI-powered failure summary (Capawesome Cloud Assist) if the build fails.'),
         gitRef: z.string().optional().describe('The Git reference (branch, tag, or commit SHA) to build.'),
         ipa: z
             .union([z.boolean(), z.string()])
@@ -94,6 +99,11 @@ export default defineCommand({
             consola.error('The --detached flag cannot be used with --channel or --destination flags.');
             process.exit(1);
         }
+        // Validate that detached flag cannot be used with failure summary
+        if (options.detached && options.failureSummary) {
+            consola.error('The --detached flag cannot be used with --failure-summary.');
+            process.exit(1);
+        }
         // Validate that channel and destination cannot be used together
         if (options.channel && options.destination) {
             consola.error('The --channel and --destination flags cannot be used together.');
@@ -328,7 +338,14 @@ export default defineCommand({
         // Wait for build job to complete by default, unless --detached flag is set
         const shouldWait = !options.detached;
         if (shouldWait) {
-            await waitForJobCompletion({ jobId: response.jobId });
+            await waitForJobCompletion({
+                jobId: response.jobId,
+                onFailed: () => offerJobFailureSummary({
+                    jobId: response.jobId,
+                    requested: !!options.failureSummary,
+                    command: `npx @capawesome/cli apps:builds:failure-summary --app-id ${appId} --build-id ${response.id}`,
+                }),
+            });
             const appBuild = await appBuildsService.findOne({
                 appId,
                 appBuildId: response.id,

package/dist/commands/apps/builds/failure-summary.js

@@ -0,0 +1,73 @@
+import appBuildsService from '../../../services/app-builds.js';
+import { withAuth } from '../../../utils/auth.js';
+import { isInteractive } from '../../../utils/environment.js';
+import { printJobFailureSummary } from '../../../utils/job-failure-summary.js';
+import { prompt, promptAppSelection, promptOrganizationSelection } from '../../../utils/prompt.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Explain why an app build failed using Capawesome Cloud Assist (AI).',
+    options: defineOptions(z.object({
+        appId: z
+            .uuid({
+            message: 'App ID must be a UUID.',
+        })
+            .optional()
+            .describe('App ID of the build to summarize.'),
+        buildId: z
+            .uuid({
+            message: 'Build ID must be a UUID.',
+        })
+            .optional()
+            .describe('Build ID to summarize.'),
+        buildNumber: z.string().optional().describe('Build number to summarize (e.g., "1", "42").'),
+    })),
+    action: withAuth(async (options) => {
+        let { appId, buildId, buildNumber } = options;
+        // Prompt for app ID if not provided
+        if (!appId) {
+            if (!isInteractive()) {
+                consola.error('You must provide an app ID when running in non-interactive environment.');
+                process.exit(1);
+            }
+            const organizationId = await promptOrganizationSelection();
+            appId = await promptAppSelection(organizationId);
+        }
+        // Convert build number to build ID if provided
+        if (!buildId && buildNumber) {
+            const builds = await appBuildsService.findAll({ appId, numberAsString: buildNumber });
+            if (builds.length === 0) {
+                consola.error(`Build #${buildNumber} not found.`);
+                process.exit(1);
+            }
+            buildId = builds[0]?.id;
+        }
+        // Prompt for build ID if not provided
+        if (!buildId) {
+            if (!isInteractive()) {
+                consola.error('You must provide a build ID when running in non-interactive environment.');
+                process.exit(1);
+            }
+            const appBuilds = await appBuildsService.findAll({ appId });
+            if (appBuilds.length === 0) {
+                consola.error('There are no builds for this app.');
+                process.exit(1);
+            }
+            // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
+            buildId = await prompt('Which build do you want a failure summary for?', {
+                type: 'select',
+                options: appBuilds.map((build) => ({
+                    label: `Build #${build.numberAsString} (${build.platform} - ${build.type})`,
+                    value: build.id,
+                })),
+            });
+            if (!buildId) {
+                consola.error('You must select a build.');
+                process.exit(1);
+            }
+        }
+        const build = await appBuildsService.findOne({ appId, appBuildId: buildId });
+        await printJobFailureSummary({ jobId: build.jobId });
+    }),
+});

package/dist/commands/apps/deployments/create.js

@@ -4,6 +4,7 @@ import appDeploymentsService from '../../../services/app-deployments.js';
 import appDestinationsService from '../../../services/app-destinations.js';
 import { withAuth } from '../../../utils/auth.js';
 import { isInteractive } from '../../../utils/environment.js';
+import { offerJobFailureSummary } from '../../../utils/job-failure-summary.js';
 import { waitForJobCompletion } from '../../../utils/job.js';
 import { prompt, promptAppSelection, promptOrganizationSelection } from '../../../utils/prompt.js';
 import { defineCommand, defineOptions } from '@robingenz/zli';
@@ -31,6 +32,10 @@ export default defineCommand({
             .boolean()
             .optional()
             .describe('Exit immediately after creating the deployment without waiting for completion.'),
+        failureSummary: z
+            .boolean()
+            .optional()
+            .describe('Request an AI-powered failure summary (Capawesome Cloud Assist) if the deployment fails.'),
     })),
     action: withAuth(async (options) => {
         let { appId, buildId, buildNumber, channel, destination } = options;
@@ -158,7 +163,14 @@ export default defineCommand({
         // Wait for deployment job to complete by default, unless --detached flag is set
         const shouldWait = !options.detached && build.platform !== 'web';
         if (shouldWait) {
-            await waitForJobCompletion({ jobId: response.jobId });
+            await waitForJobCompletion({
+                jobId: response.jobId,
+                onFailed: () => offerJobFailureSummary({
+                    jobId: response.jobId,
+                    requested: !!options.failureSummary,
+                    command: `npx @capawesome/cli apps:deployments:failure-summary --app-id ${appId} --deployment-id ${response.id}`,
+                }),
+            });
             consola.success('Deployment completed successfully.');
             process.exit(0);
         }

package/dist/commands/apps/deployments/failure-summary.js

@@ -0,0 +1,63 @@
+import appDeploymentsService from '../../../services/app-deployments.js';
+import { withAuth } from '../../../utils/auth.js';
+import { isInteractive } from '../../../utils/environment.js';
+import { printJobFailureSummary } from '../../../utils/job-failure-summary.js';
+import { prompt, promptAppSelection, promptOrganizationSelection } from '../../../utils/prompt.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Explain why an app deployment failed using Capawesome Cloud Assist (AI).',
+    options: defineOptions(z.object({
+        appId: z
+            .uuid({
+            message: 'App ID must be a UUID.',
+        })
+            .optional()
+            .describe('App ID of the deployment to summarize.'),
+        deploymentId: z
+            .uuid({
+            message: 'Deployment ID must be a UUID.',
+        })
+            .optional()
+            .describe('Deployment ID to summarize.'),
+    })),
+    action: withAuth(async (options) => {
+        let { appId, deploymentId } = options;
+        // Prompt for app ID if not provided
+        if (!appId) {
+            if (!isInteractive()) {
+                consola.error('You must provide an app ID when running in non-interactive environment.');
+                process.exit(1);
+            }
+            const organizationId = await promptOrganizationSelection();
+            appId = await promptAppSelection(organizationId);
+        }
+        // Prompt for deployment ID if not provided
+        if (!deploymentId) {
+            if (!isInteractive()) {
+                consola.error('You must provide a deployment ID when running in non-interactive environment.');
+                process.exit(1);
+            }
+            const appDeployments = await appDeploymentsService.findAll({ appId });
+            if (appDeployments.length === 0) {
+                consola.error('There are no deployments for this app.');
+                process.exit(1);
+            }
+            // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
+            deploymentId = await prompt('Which deployment do you want a failure summary for?', {
+                type: 'select',
+                options: appDeployments.map((deployment) => ({
+                    label: `Deployment ${deployment.id}`,
+                    value: deployment.id,
+                })),
+            });
+            if (!deploymentId) {
+                consola.error('You must select a deployment.');
+                process.exit(1);
+            }
+        }
+        const deployment = await appDeploymentsService.findOne({ appId, appDeploymentId: deploymentId });
+        await printJobFailureSummary({ jobId: deployment.jobId });
+    }),
+});

package/dist/commands/apps/environments/get.js

@@ -0,0 +1,62 @@
+import appEnvironmentsService from '../../../services/app-environments.js';
+import { withAuth } from '../../../utils/auth.js';
+import { isInteractive } from '../../../utils/environment.js';
+import { prompt, promptAppSelection, promptOrganizationSelection } from '../../../utils/prompt.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Get an existing environment.',
+    options: defineOptions(z.object({
+        appId: z.string().optional().describe('ID of the app.'),
+        environmentId: z.string().optional().describe('ID of the environment. Either the ID or name must be provided.'),
+        name: z.string().optional().describe('Name of the environment. Either the ID or name must be provided.'),
+        json: z.boolean().optional().describe('Output in JSON format.'),
+    })),
+    action: withAuth(async (options, args) => {
+        let { appId, environmentId, name, json } = options;
+        if (!appId) {
+            if (!isInteractive()) {
+                consola.error('You must provide an app ID when running in non-interactive environment.');
+                process.exit(1);
+            }
+            const organizationId = await promptOrganizationSelection();
+            appId = await promptAppSelection(organizationId);
+        }
+        if (!environmentId && !name) {
+            if (!isInteractive()) {
+                consola.error('You must provide either the environment ID or name when running in non-interactive environment.');
+                process.exit(1);
+            }
+            const environments = await appEnvironmentsService.findAll({ appId });
+            if (!environments.length) {
+                consola.error('No environments found for this app. Create one first.');
+                process.exit(1);
+            }
+            // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
+            environmentId = await prompt('Select the environment:', {
+                type: 'select',
+                options: environments.map((env) => ({ label: env.name, value: env.id })),
+            });
+        }
+        let environment;
+        if (environmentId) {
+            environment = await appEnvironmentsService.findOneById({ appId, id: environmentId });
+        }
+        else if (name) {
+            const environments = await appEnvironmentsService.findAll({ appId, name });
+            environment = environments[0];
+        }
+        if (!environment) {
+            consola.error('Environment not found.');
+            process.exit(1);
+        }
+        if (json) {
+            console.log(JSON.stringify(environment, null, 2));
+        }
+        else {
+            console.table(environment);
+            consola.success('Environment retrieved successfully.');
+        }
+    }),
+});

package/dist/commands/apps/environments/set.js

@@ -12,7 +12,8 @@ export default defineCommand({
     description: 'Set environment variables and secrets.',
     options: defineOptions(z.object({
         appId: z.string().optional().describe('ID of the app.'),
-        environmentId: z.string().optional().describe('ID of the environment.'),
+        environmentId: z.string().optional().describe('ID of the environment. Either the ID or name must be provided.'),
+        name: z.string().optional().describe('Name of the environment. Either the ID or name must be provided.'),
         variable: z
             .array(z.string())
             .optional()
@@ -25,7 +26,7 @@ export default defineCommand({
         secretFile: z.string().optional().describe('Path to a file containing environment secrets in .env format.'),
     })),
     action: withAuth(async (options, args) => {
-        let { appId, environmentId, variable, variableFile, secret, secretFile } = options;
+        let { appId, environmentId, name, variable, variableFile, secret, secretFile } = options;
         if (!appId) {
             if (!isInteractive()) {
                 consola.error('You must provide an app ID when running in non-interactive environment.');
@@ -35,20 +36,31 @@ export default defineCommand({
             appId = await promptAppSelection(organizationId);
         }
         if (!environmentId) {
-            if (!isInteractive()) {
-                consola.error('You must provide an environment ID when running in non-interactive environment.');
-                process.exit(1);
+            if (name) {
+                const environments = await appEnvironmentsService.findAll({ appId, name });
+                const environment = environments[0];
+                if (!environment) {
+                    consola.error('Environment not found.');
+                    process.exit(1);
+                }
+                environmentId = environment.id;
             }
-            const environments = await appEnvironmentsService.findAll({ appId });
-            if (!environments.length) {
-                consola.error('No environments found for this app. Create one first.');
-                process.exit(1);
+            else {
+                if (!isInteractive()) {
+                    consola.error('You must provide either the environment ID or name when running in non-interactive environment.');
+                    process.exit(1);
+                }
+                const environments = await appEnvironmentsService.findAll({ appId });
+                if (!environments.length) {
+                    consola.error('No environments found for this app. Create one first.');
+                    process.exit(1);
+                }
+                // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
+                environmentId = await prompt('Select the environment:', {
+                    type: 'select',
+                    options: environments.map((env) => ({ label: env.name, value: env.id })),
+                });
             }
-            // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
-            environmentId = await prompt('Select the environment:', {
-                type: 'select',
-                options: environments.map((env) => ({ label: env.name, value: env.id })),
-            });
         }
         // Parse variables from inline and file
         const variablesMap = new Map();

package/dist/commands/apps/environments/unset.js

@@ -9,7 +9,8 @@ export default defineCommand({
     description: 'Unset environment variables and secrets.',
     options: defineOptions(z.object({
         appId: z.string().optional().describe('ID of the app.'),
-        environmentId: z.string().optional().describe('ID of the environment.'),
+        environmentId: z.string().optional().describe('ID of the environment. Either the ID or name must be provided.'),
+        name: z.string().optional().describe('Name of the environment. Either the ID or name must be provided.'),
         variable: z
             .array(z.string())
             .optional()
@@ -20,7 +21,7 @@ export default defineCommand({
             .describe('Key of the environment secret to unset. Can be specified multiple times.'),
     })),
     action: withAuth(async (options, args) => {
-        let { appId, environmentId, variable: variableKeys, secret: secretKeys } = options;
+        let { appId, environmentId, name, variable: variableKeys, secret: secretKeys } = options;
         if (!appId) {
             if (!isInteractive()) {
                 consola.error('You must provide an app ID when running in non-interactive environment.');
@@ -30,20 +31,31 @@ export default defineCommand({
             appId = await promptAppSelection(organizationId);
         }
         if (!environmentId) {
-            if (!isInteractive()) {
-                consola.error('You must provide an environment ID when running in non-interactive environment.');
-                process.exit(1);
+            if (name) {
+                const environments = await appEnvironmentsService.findAll({ appId, name });
+                const environment = environments[0];
+                if (!environment) {
+                    consola.error('Environment not found.');
+                    process.exit(1);
+                }
+                environmentId = environment.id;
             }
-            const environments = await appEnvironmentsService.findAll({ appId });
-            if (!environments.length) {
-                consola.error('No environments found for this app. Create one first.');
-                process.exit(1);
+            else {
+                if (!isInteractive()) {
+                    consola.error('You must provide either the environment ID or name when running in non-interactive environment.');
+                    process.exit(1);
+                }
+                const environments = await appEnvironmentsService.findAll({ appId });
+                if (!environments.length) {
+                    consola.error('No environments found for this app. Create one first.');
+                    process.exit(1);
+                }
+                // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
+                environmentId = await prompt('Select the environment:', {
+                    type: 'select',
+                    options: environments.map((env) => ({ label: env.name, value: env.id })),
+                });
             }
-            // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
-            environmentId = await prompt('Select the environment:', {
-                type: 'select',
-                options: environments.map((env) => ({ label: env.name, value: env.id })),
-            });
         }
         if (!variableKeys?.length && !secretKeys?.length) {
             consola.error('You must provide at least one variable key or secret key to unset.');

package/dist/commands/apps/liveupdates/generate-signing-key.js

@@ -3,9 +3,16 @@ import consola from 'consola';
 import { promises as fs } from 'fs';
 import pathModule from 'path';
 import { z } from 'zod';
+import { isInteractive } from '../../../utils/environment.js';
+import { prompt } from '../../../utils/prompt.js';
+const APP_TYPES = ['capacitor', 'cordova'];
 export default defineCommand({
     description: 'Generate a new code signing key pair for Live Updates.',
     options: defineOptions(z.object({
+        appType: z
+            .enum(APP_TYPES)
+            .optional()
+            .describe('The app type to configure code signing for. Either `capacitor` or `cordova`.'),
         publicKeyPath: z
             .string()
             .optional()
@@ -54,21 +61,14 @@ export default defineCommand({
             consola.log('Private key saved to: ' + absolutePrivateKeyPath);
             consola.log('');
             consola.warn('IMPORTANT: Keep your private key safe and never commit it to version control!');
+            const appType = await resolveAppType(options.appType);
+            if (appType) {
+                // Format the public key for JSON output (remove line breaks)
+                const publicKeyForJson = publicKey.replace(/\n/g, '');
+                consola.log('');
+                printSigningKeyConfig(appType, publicKeyForJson);
+            }
             consola.log('');
-            consola.log('To configure code signing in the Capacitor Live Update plugin, add the following to your Capacitor Configuration file:');
-            consola.log('');
-            // Format the public key for JSON output (remove line breaks)
-            const publicKeyForJson = publicKey.replace(/\n/g, '');
-            // Print the JSON configuration
-            const config = {
-                plugins: {
-                    LiveUpdate: {
-                        publicKey: publicKeyForJson,
-                    },
-                },
-            };
-            consola.log(JSON.stringify(config, null, 2));
-            console.log('');
             consola.success('Code signing key pair generated successfully!');
         }
         catch (error) {
@@ -77,3 +77,48 @@ export default defineCommand({
         }
     },
 });
+const resolveAppType = async (appType) => {
+    if (appType) {
+        return appType;
+    }
+    if (!isInteractive()) {
+        return undefined;
+    }
+    // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
+    return prompt('Which app type do you want to configure code signing for?', {
+        type: 'select',
+        options: [
+            { label: 'Capacitor', value: 'capacitor' },
+            { label: 'Cordova', value: 'cordova' },
+        ],
+    });
+};
+const printSigningKeyConfig = (appType, publicKey) => {
+    if (appType === 'cordova') {
+        const config = {
+            cordova: {
+                plugins: {
+                    '@capawesome/cordova-live-update': {
+                        PUBLIC_KEY: publicKey,
+                    },
+                },
+            },
+        };
+        consola.log('To configure code signing in the Cordova Live Update plugin, add the following to your `package.json` file:');
+        consola.log('');
+        consola.log(JSON.stringify(config, null, 2));
+        consola.log('');
+        consola.warn('If the plugin has already been added, you must re-add it for the changes to take effect.');
+        return;
+    }
+    const config = {
+        plugins: {
+            LiveUpdate: {
+                publicKey,
+            },
+        },
+    };
+    consola.log('To configure code signing in the Capacitor Live Update plugin, add the following to your Capacitor configuration file:');
+    consola.log('');
+    consola.log(JSON.stringify(config, null, 2));
+};

package/dist/index.js

@@ -30,6 +30,7 @@ const config = defineConfig({
         'apps:unlink': await import('./commands/apps/unlink.js').then((mod) => mod.default),
         'apps:builds:cancel': await import('./commands/apps/builds/cancel.js').then((mod) => mod.default),
         'apps:builds:create': await import('./commands/apps/builds/create.js').then((mod) => mod.default),
+        'apps:builds:failure-summary': await import('./commands/apps/builds/failure-summary.js').then((mod) => mod.default),
         'apps:builds:get': await import('./commands/apps/builds/get.js').then((mod) => mod.default),
         'apps:builds:list': await import('./commands/apps/builds/list.js').then((mod) => mod.default),
         'apps:builds:logs': await import('./commands/apps/builds/logs.js').then((mod) => mod.default),
@@ -51,6 +52,7 @@ const config = defineConfig({
         'apps:channels:update': await import('./commands/apps/channels/update.js').then((mod) => mod.default),
         'apps:deployments:create': await import('./commands/apps/deployments/create.js').then((mod) => mod.default),
         'apps:deployments:cancel': await import('./commands/apps/deployments/cancel.js').then((mod) => mod.default),
+        'apps:deployments:failure-summary': await import('./commands/apps/deployments/failure-summary.js').then((mod) => mod.default),
         'apps:deployments:get': await import('./commands/apps/deployments/get.js').then((mod) => mod.default),
         'apps:deployments:list': await import('./commands/apps/deployments/list.js').then((mod) => mod.default),
         'apps:deployments:logs': await import('./commands/apps/deployments/logs.js').then((mod) => mod.default),
@@ -65,6 +67,7 @@ const config = defineConfig({
         'apps:devices:unforcechannel': await import('./commands/apps/devices/unforcechannel.js').then((mod) => mod.default),
         'apps:environments:create': await import('./commands/apps/environments/create.js').then((mod) => mod.default),
         'apps:environments:delete': await import('./commands/apps/environments/delete.js').then((mod) => mod.default),
+        'apps:environments:get': await import('./commands/apps/environments/get.js').then((mod) => mod.default),
         'apps:environments:list': await import('./commands/apps/environments/list.js').then((mod) => mod.default),
         'apps:environments:set': await import('./commands/apps/environments/set.js').then((mod) => mod.default),
         'apps:environments:unset': await import('./commands/apps/environments/unset.js').then((mod) => mod.default),

package/dist/services/app-environments.js

@@ -34,6 +34,9 @@ class AppEnvironmentsServiceImpl {
     }
     async findAll(dto) {
         const queryParams = new URLSearchParams();
+        if (dto.name) {
+            queryParams.append('name', dto.name);
+        }
         if (dto.limit) {
             queryParams.append('limit', dto.limit.toString());
         }
@@ -51,6 +54,14 @@ class AppEnvironmentsServiceImpl {
         });
         return response.data;
     }
+    async findOneById(dto) {
+        const response = await this.httpClient.get(`/v1/apps/${dto.appId}/environments/${dto.id}`, {
+            headers: {
+                Authorization: `Bearer ${authorizationService.getCurrentAuthorizationToken()}`,
+            },
+        });
+        return response.data;
+    }
     async setVariables(dto) {
         await this.httpClient.post(`/v1/apps/${dto.appId}/environments/${dto.environmentId}/variables/set`, dto.variables, {
             headers: {

package/dist/services/jobs.js

@@ -18,6 +18,14 @@ class JobsServiceImpl {
         });
         return response.data;
     }
+    async generateFailureSummary(dto) {
+        const response = await this.httpClient.post(`/v1/jobs/${dto.jobId}/failure-summary`, undefined, {
+            headers: {
+                Authorization: `Bearer ${authorizationService.getCurrentAuthorizationToken()}`,
+            },
+        });
+        return response.data;
+    }
     async update(options) {
         const { jobId, dto } = options;
         const response = await this.httpClient.patch(`/v1/jobs/${jobId}`, dto, {

package/dist/utils/job-failure-summary.js

@@ -0,0 +1,58 @@
+import jobsService from '../services/jobs.js';
+import { isInteractive } from '../utils/environment.js';
+import { prompt } from '../utils/prompt.js';
+import consola from 'consola';
+/**
+ * Request an AI-powered failure summary for a failed job and print it.
+ *
+ * Powered by Capawesome Cloud Assist. The summary is printed as plain text so
+ * the terminal can soft-wrap it to any width.
+ */
+export const printJobFailureSummary = async (options) => {
+    const { jobId } = options;
+    consola.start('Generating failure summary with Capawesome Cloud Assist...');
+    const { summary } = await jobsService.generateFailureSummary({ jobId });
+    consola.success('Failure summary generated by Capawesome Cloud Assist:');
+    console.log();
+    console.log(summary);
+};
+/**
+ * Best-effort variant of {@link printJobFailureSummary}.
+ *
+ * Warns instead of throwing so that it never masks the underlying job failure.
+ */
+const tryPrintJobFailureSummary = async (options) => {
+    try {
+        await printJobFailureSummary(options);
+    }
+    catch {
+        consola.warn('Could not generate a failure summary at this time.');
+    }
+};
+/**
+ * Offer an AI-powered failure summary after a job has failed.
+ *
+ * - If the summary was requested up front, it is generated right away.
+ * - Otherwise, the user is asked whether they want one (interactive), or
+ *   pointed to the command that generates it (non-interactive).
+ */
+export const offerJobFailureSummary = async (options) => {
+    const { jobId, requested, command } = options;
+    if (requested) {
+        await tryPrintJobFailureSummary({ jobId });
+        return;
+    }
+    if (isInteractive()) {
+        // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
+        const wantsSummary = await prompt('Do you want Capawesome Cloud Assist to explain what went wrong?', {
+            type: 'confirm',
+            initial: false,
+        });
+        if (wantsSummary) {
+            await tryPrintJobFailureSummary({ jobId });
+        }
+    }
+    else {
+        consola.info(`Need help? Run \`${command}\` for an AI-powered failure summary.`);
+    }
+};

package/dist/utils/job.js

@@ -52,6 +52,14 @@ export const waitForJobCompletion = async (options) => {
                 }
                 else if (jobStatus === 'failed') {
                     consola.error(`${capitalize(label)} failed.`);
+                    if (options.onFailed) {
+                        try {
+                            await options.onFailed(job);
+                        }
+                        catch {
+                            // Ignore errors from the failure handler -- the job failure is what matters.
+                        }
+                    }
                     process.exit(1);
                 }
                 else if (jobStatus === 'canceled') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capawesome/cli",
-  "version": "4.11.0",
+  "version": "4.12.0",
   "description": "The Capawesome Cloud Command Line Interface (CLI) to manage Live Updates and more.",
   "type": "module",
   "scripts": {