@capawesome/cli 4.8.3 → 4.9.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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.9.0](https://github.com/capawesome-team/cli/compare/v4.8.3...v4.9.0) (2026-05-01)
+
+
+### Features
+
+* add `get`/`list` commands for apps, builds, deployments, and organizations ([#156](https://github.com/capawesome-team/cli/issues/156)) ([32363d4](https://github.com/capawesome-team/cli/commit/32363d4f7d44bc0d7036f9062a1d74c01e15dfed))
+* **apps:** add `--type` option to `apps:create` ([#154](https://github.com/capawesome-team/cli/issues/154)) ([c23c877](https://github.com/capawesome-team/cli/commit/c23c8775359de0841ce57904dc4c75b9420fad04))
+
+
+### Bug Fixes
+
+* surface actionable error when config file is not writable ([#153](https://github.com/capawesome-team/cli/issues/153)) ([ab8ed4c](https://github.com/capawesome-team/cli/commit/ab8ed4cb33ab02c5e5db62140ca3501b02e263b4))
+
 ## [4.8.3](https://github.com/capawesome-team/cli/compare/v4.8.2...v4.8.3) (2026-04-20)
 
 

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

@@ -0,0 +1,36 @@
+import appBuildsService from '../../../services/app-builds.js';
+import { withAuth } from '../../../utils/auth.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Get an existing app build.',
+    options: defineOptions(z.object({
+        appId: z.string().optional().describe('ID of the app.'),
+        buildId: z.string().optional().describe('ID of the build.'),
+        json: z.boolean().optional().describe('Output in JSON format.'),
+    })),
+    action: withAuth(async (options, args) => {
+        const { appId, buildId, json } = options;
+        if (!appId) {
+            consola.error('You must provide an app ID.');
+            process.exit(1);
+        }
+        if (!buildId) {
+            consola.error('You must provide a build ID.');
+            process.exit(1);
+        }
+        const build = await appBuildsService.findOne({
+            appId,
+            appBuildId: buildId,
+            relations: json ? 'job' : undefined,
+        });
+        if (json) {
+            console.log(JSON.stringify(build, null, 2));
+        }
+        else {
+            console.table(build);
+            consola.success('Build retrieved successfully.');
+        }
+    }),
+});

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

@@ -0,0 +1,44 @@
+import appBuildsService from '../../../services/app-builds.js';
+import { withAuth } from '../../../utils/auth.js';
+import { isInteractive } from '../../../utils/environment.js';
+import { promptAppSelection, promptOrganizationSelection } from '../../../utils/prompt.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Retrieve a list of existing app builds.',
+    options: defineOptions(z.object({
+        appId: z.string().optional().describe('ID of the app.'),
+        json: z.boolean().optional().describe('Output in JSON format.'),
+        limit: z.coerce.number().optional().describe('Limit for pagination.'),
+        numberAsString: z.string().optional().describe('Build number to filter by.'),
+        offset: z.coerce.number().optional().describe('Offset for pagination.'),
+        platform: z.enum(['android', 'ios', 'web']).optional().describe('Platform to filter by.'),
+    })),
+    action: withAuth(async (options, args) => {
+        let { appId, json, limit, numberAsString, offset, platform } = 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);
+        }
+        const foundBuilds = await appBuildsService.findAll({
+            appId,
+            limit,
+            numberAsString,
+            offset,
+            platform,
+            relations: json ? 'job' : undefined,
+        });
+        if (json) {
+            console.log(JSON.stringify(foundBuilds, null, 2));
+        }
+        else {
+            console.table(foundBuilds);
+            consola.success('Builds retrieved successfully.');
+        }
+    }),
+});

package/dist/commands/apps/create.js

@@ -13,10 +13,15 @@ export default defineCommand({
         link: z.boolean().optional().describe('Connect the created app to the local git repository.'),
         name: z.string().optional().describe('Name of the app.'),
         organizationId: z.string().optional().describe('ID of the organization to create the app in.'),
+        type: z
+            .enum(['android', 'capacitor', 'cordova', 'ios'])
+            .optional()
+            .describe('Type of the app. Defaults to `capacitor`.'),
         yes: z.boolean().optional().describe('Skip all confirmation prompts.'),
     }), { y: 'yes' }),
     action: withAuth(async (options, args) => {
         let { json, name, organizationId } = options;
+        const type = options.type ?? 'capacitor';
         if (!organizationId) {
             if (!isInteractive()) {
                 consola.error('You must provide the organization ID when running in non-interactive environment.');
@@ -31,7 +36,7 @@ export default defineCommand({
             }
             name = await prompt('Enter the name of the app:', { type: 'text' });
         }
-        const response = await appsService.create({ name, organizationId });
+        const response = await appsService.create({ name, organizationId, type });
         if (!json) {
             consola.info(`App ID: ${response.id}`);
             consola.info(`App URL: ${DEFAULT_CONSOLE_BASE_URL}/apps/${response.id}`);

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

@@ -38,9 +38,9 @@ describe('apps-create', () => {
         const organizationId = 'org-123';
         const appId = 'app-456';
         const testToken = 'test-token';
-        const options = { name: appName, organizationId };
+        const options = { name: appName, organizationId, type: 'capacitor' };
         const scope = nock(DEFAULT_API_BASE_URL)
-            .post(`/v1/apps?organizationId=${organizationId}`, { name: appName })
+            .post(`/v1/apps?organizationId=${organizationId}`, { name: appName, type: 'capacitor' })
             .matchHeader('Authorization', `Bearer ${testToken}`)
             .reply(201, { id: appId, name: appName });
         await createAppCommand.action(options, undefined);
@@ -53,9 +53,9 @@ describe('apps-create', () => {
         const orgId = 'org-1';
         const appId = 'app-456';
         const testToken = 'test-token';
-        const options = { name: appName };
+        const options = { name: appName, type: 'capacitor' };
         const createScope = nock(DEFAULT_API_BASE_URL)
-            .post(`/v1/apps?organizationId=${orgId}`, { name: appName })
+            .post(`/v1/apps?organizationId=${orgId}`, { name: appName, type: 'capacitor' })
             .matchHeader('Authorization', `Bearer ${testToken}`)
             .reply(201, { id: appId, name: appName });
         mockPromptOrganizationSelection.mockResolvedValueOnce(orgId);
@@ -69,9 +69,9 @@ describe('apps-create', () => {
         const promptedAppName = 'Prompted App';
         const appId = 'app-456';
         const testToken = 'test-token';
-        const options = { organizationId };
+        const options = { organizationId, type: 'capacitor' };
         const scope = nock(DEFAULT_API_BASE_URL)
-            .post(`/v1/apps?organizationId=${organizationId}`, { name: promptedAppName })
+            .post(`/v1/apps?organizationId=${organizationId}`, { name: promptedAppName, type: 'capacitor' })
             .matchHeader('Authorization', `Bearer ${testToken}`)
             .reply(201, { id: appId, name: promptedAppName });
         mockPrompt.mockResolvedValueOnce(promptedAppName);
@@ -80,7 +80,7 @@ describe('apps-create', () => {
         expect(mockPrompt).toHaveBeenCalledWith('Enter the name of the app:', { type: 'text' });
     });
     it('should exit when promptOrganizationSelection exits', async () => {
-        const options = { name: 'Test App' };
+        const options = { name: 'Test App', type: 'capacitor' };
         mockPromptOrganizationSelection.mockImplementation(() => {
             process.exit(1);
             return Promise.resolve('');
@@ -91,9 +91,9 @@ describe('apps-create', () => {
         const appName = 'Test App';
         const organizationId = 'org-123';
         const testToken = 'test-token';
-        const options = { name: appName, organizationId };
+        const options = { name: appName, organizationId, type: 'capacitor' };
         const scope = nock(DEFAULT_API_BASE_URL)
-            .post(`/v1/apps?organizationId=${organizationId}`, { name: appName })
+            .post(`/v1/apps?organizationId=${organizationId}`, { name: appName, type: 'capacitor' })
             .matchHeader('Authorization', `Bearer ${testToken}`)
             .reply(400, { message: 'App name already exists' });
         await expect(createAppCommand.action(options, undefined)).rejects.toThrow();

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

@@ -0,0 +1,36 @@
+import appDeploymentsService from '../../../services/app-deployments.js';
+import { withAuth } from '../../../utils/auth.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Get an existing app deployment.',
+    options: defineOptions(z.object({
+        appId: z.string().optional().describe('ID of the app.'),
+        deploymentId: z.string().optional().describe('ID of the deployment.'),
+        json: z.boolean().optional().describe('Output in JSON format.'),
+    })),
+    action: withAuth(async (options, args) => {
+        const { appId, deploymentId, json } = options;
+        if (!appId) {
+            consola.error('You must provide an app ID.');
+            process.exit(1);
+        }
+        if (!deploymentId) {
+            consola.error('You must provide a deployment ID.');
+            process.exit(1);
+        }
+        const deployment = await appDeploymentsService.findOne({
+            appId,
+            appDeploymentId: deploymentId,
+            relations: json ? 'job' : undefined,
+        });
+        if (json) {
+            console.log(JSON.stringify(deployment, null, 2));
+        }
+        else {
+            console.table(deployment);
+            consola.success('Deployment retrieved successfully.');
+        }
+    }),
+});

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

@@ -0,0 +1,46 @@
+import appDeploymentsService from '../../../services/app-deployments.js';
+import { withAuth } from '../../../utils/auth.js';
+import { isInteractive } from '../../../utils/environment.js';
+import { promptAppSelection, promptOrganizationSelection } from '../../../utils/prompt.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Retrieve a list of existing app deployments.',
+    options: defineOptions(z.object({
+        appId: z.string().optional().describe('ID of the app.'),
+        buildId: z.string().optional().describe('ID of the build to filter by.'),
+        channelId: z.string().optional().describe('ID of the channel to filter by.'),
+        destinationId: z.string().optional().describe('ID of the destination to filter by.'),
+        json: z.boolean().optional().describe('Output in JSON format.'),
+        limit: z.coerce.number().optional().describe('Limit for pagination.'),
+        offset: z.coerce.number().optional().describe('Offset for pagination.'),
+    })),
+    action: withAuth(async (options, args) => {
+        let { appId, buildId, channelId, destinationId, json, limit, offset } = 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);
+        }
+        const foundDeployments = await appDeploymentsService.findAll({
+            appId,
+            appBuildId: buildId,
+            appChannelId: channelId,
+            appDestinationId: destinationId,
+            limit,
+            offset,
+            relations: json ? 'job' : undefined,
+        });
+        if (json) {
+            console.log(JSON.stringify(foundDeployments, null, 2));
+        }
+        else {
+            console.table(foundDeployments);
+            consola.success('Deployments retrieved successfully.');
+        }
+    }),
+});

package/dist/commands/apps/get.js

@@ -0,0 +1,27 @@
+import appsService from '../../services/apps.js';
+import { withAuth } from '../../utils/auth.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Get an existing app.',
+    options: defineOptions(z.object({
+        appId: z.string().optional().describe('ID of the app.'),
+        json: z.boolean().optional().describe('Output in JSON format.'),
+    })),
+    action: withAuth(async (options, args) => {
+        const { appId, json } = options;
+        if (!appId) {
+            consola.error('You must provide an app ID.');
+            process.exit(1);
+        }
+        const app = await appsService.findOne({ appId });
+        if (json) {
+            console.log(JSON.stringify(app, null, 2));
+        }
+        else {
+            console.table(app);
+            consola.success('App retrieved successfully.');
+        }
+    }),
+});

package/dist/commands/apps/list.js

@@ -0,0 +1,38 @@
+import appsService from '../../services/apps.js';
+import { withAuth } from '../../utils/auth.js';
+import { isInteractive } from '../../utils/environment.js';
+import { promptOrganizationSelection } from '../../utils/prompt.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Retrieve a list of existing apps.',
+    options: defineOptions(z.object({
+        json: z.boolean().optional().describe('Output in JSON format.'),
+        limit: z.coerce.number().optional().describe('Limit for pagination.'),
+        offset: z.coerce.number().optional().describe('Offset for pagination.'),
+        organizationId: z.string().optional().describe('ID of the organization.'),
+    })),
+    action: withAuth(async (options, args) => {
+        let { json, limit, offset, organizationId } = options;
+        if (!organizationId) {
+            if (!isInteractive()) {
+                consola.error('You must provide an organization ID when running in non-interactive environment.');
+                process.exit(1);
+            }
+            organizationId = await promptOrganizationSelection();
+        }
+        const foundApps = await appsService.findAll({
+            organizationId,
+            limit,
+            offset,
+        });
+        if (json) {
+            console.log(JSON.stringify(foundApps, null, 2));
+        }
+        else {
+            console.table(foundApps);
+            consola.success('Apps retrieved successfully.');
+        }
+    }),
+});

package/dist/commands/organizations/get.js

@@ -0,0 +1,27 @@
+import organizationsService from '../../services/organizations.js';
+import { withAuth } from '../../utils/auth.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Get an existing organization.',
+    options: defineOptions(z.object({
+        json: z.boolean().optional().describe('Output in JSON format.'),
+        organizationId: z.string().optional().describe('ID of the organization.'),
+    })),
+    action: withAuth(async (options, args) => {
+        const { json, organizationId } = options;
+        if (!organizationId) {
+            consola.error('You must provide an organization ID.');
+            process.exit(1);
+        }
+        const organization = await organizationsService.findOne({ organizationId });
+        if (json) {
+            console.log(JSON.stringify(organization, null, 2));
+        }
+        else {
+            console.table(organization);
+            consola.success('Organization retrieved successfully.');
+        }
+    }),
+});

package/dist/commands/organizations/list.js

@@ -0,0 +1,27 @@
+import organizationsService from '../../services/organizations.js';
+import { withAuth } from '../../utils/auth.js';
+import { defineCommand, defineOptions } from '@robingenz/zli';
+import consola from 'consola';
+import { z } from 'zod';
+export default defineCommand({
+    description: 'Retrieve a list of existing organizations.',
+    options: defineOptions(z.object({
+        json: z.boolean().optional().describe('Output in JSON format.'),
+        limit: z.coerce.number().optional().describe('Limit for pagination.'),
+        offset: z.coerce.number().optional().describe('Offset for pagination.'),
+    })),
+    action: withAuth(async (options, args) => {
+        const { json, limit, offset } = options;
+        const foundOrganizations = await organizationsService.findAll({
+            limit,
+            offset,
+        });
+        if (json) {
+            console.log(JSON.stringify(foundOrganizations, null, 2));
+        }
+        else {
+            console.table(foundOrganizations);
+            consola.success('Organizations retrieved successfully.');
+        }
+    }),
+});

package/dist/index.js

@@ -23,11 +23,15 @@ const config = defineConfig({
         doctor: await import('./commands/doctor.js').then((mod) => mod.default),
         'apps:create': await import('./commands/apps/create.js').then((mod) => mod.default),
         'apps:delete': await import('./commands/apps/delete.js').then((mod) => mod.default),
+        'apps:get': await import('./commands/apps/get.js').then((mod) => mod.default),
         'apps:link': await import('./commands/apps/link.js').then((mod) => mod.default),
+        'apps:list': await import('./commands/apps/list.js').then((mod) => mod.default),
         'apps:transfer': await import('./commands/apps/transfer.js').then((mod) => mod.default),
         '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: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),
         'apps:builds:download': await import('./commands/apps/builds/download.js').then((mod) => mod.default),
         'apps:bundles:create': await import('./commands/apps/bundles/create.js').then((mod) => mod.default),
@@ -47,6 +51,8 @@ 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: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),
         'apps:destinations:create': await import('./commands/apps/destinations/create.js').then((mod) => mod.default),
         'apps:destinations:delete': await import('./commands/apps/destinations/delete.js').then((mod) => mod.default),
@@ -73,6 +79,8 @@ const config = defineConfig({
         'apps:liveupdates:generatemanifest': await import('./commands/apps/liveupdates/generate-manifest.js').then((mod) => mod.default),
         'manifests:generate': await import('./commands/manifests/generate.js').then((mod) => mod.default),
         'organizations:create': await import('./commands/organizations/create.js').then((mod) => mod.default),
+        'organizations:get': await import('./commands/organizations/get.js').then((mod) => mod.default),
+        'organizations:list': await import('./commands/organizations/list.js').then((mod) => mod.default),
     },
 });
 const captureException = async (error) => {

package/dist/services/app-builds.js

@@ -16,12 +16,21 @@ class AppBuildsServiceImpl {
     }
     async findAll(dto) {
         const params = {};
-        if (dto.platform) {
-            params.platform = dto.platform;
+        if (dto.limit !== undefined) {
+            params.limit = dto.limit.toString();
         }
         if (dto.numberAsString) {
             params.numberAsString = dto.numberAsString;
         }
+        if (dto.offset !== undefined) {
+            params.offset = dto.offset.toString();
+        }
+        if (dto.platform) {
+            params.platform = dto.platform;
+        }
+        if (dto.relations) {
+            params.relations = dto.relations;
+        }
         const response = await this.httpClient.get(`/v1/apps/${dto.appId}/builds`, {
             headers: {
                 Authorization: `Bearer ${authorizationService.getCurrentAuthorizationToken()}`,

package/dist/services/app-deployments.js

@@ -15,12 +15,21 @@ class AppDeploymentsServiceImpl {
     }
     async findAll(dto) {
         const params = {};
+        if (dto.appBuildId) {
+            params.appBuildId = dto.appBuildId;
+        }
         if (dto.appChannelId) {
             params.appChannelId = dto.appChannelId;
         }
-        if (dto.limit) {
+        if (dto.appDestinationId) {
+            params.appDestinationId = dto.appDestinationId;
+        }
+        if (dto.limit !== undefined) {
             params.limit = dto.limit.toString();
         }
+        if (dto.offset !== undefined) {
+            params.offset = dto.offset.toString();
+        }
         if (dto.relations) {
             params.relations = dto.relations;
         }

package/dist/services/apps.js

@@ -27,6 +27,9 @@ class AppsServiceImpl {
         if (dto.limit !== undefined) {
             params.append('limit', dto.limit.toString());
         }
+        if (dto.offset !== undefined) {
+            params.append('offset', dto.offset.toString());
+        }
         const response = await this.httpClient.get(`/v1/apps?${params.toString()}`, {
             headers: {
                 Authorization: `Bearer ${authorizationService.getCurrentAuthorizationToken()}`,

package/dist/services/organizations.js

@@ -13,11 +13,27 @@ class OrganizationsServiceImpl {
         });
         return response.data;
     }
-    async findAll() {
+    async findAll(dto) {
+        const params = {};
+        if (dto?.limit !== undefined) {
+            params.limit = dto.limit.toString();
+        }
+        if (dto?.offset !== undefined) {
+            params.offset = dto.offset.toString();
+        }
         const response = await this.httpClient.get(`/v1/organizations`, {
             headers: {
                 Authorization: `Bearer ${authorizationService.getCurrentAuthorizationToken()}`,
             },
+            params,
+        });
+        return response.data;
+    }
+    async findOne(dto) {
+        const response = await this.httpClient.get(`/v1/organizations/${dto.organizationId}`, {
+            headers: {
+                Authorization: `Bearer ${authorizationService.getCurrentAuthorizationToken()}`,
+            },
         });
         return response.data;
     }

package/dist/utils/error.js

@@ -6,6 +6,12 @@ export class UserError extends Error {
         this.name = 'UserError';
     }
 }
+export const getCodeFromUnknownError = (error) => {
+    if (error instanceof Error && 'code' in error && typeof error.code === 'string') {
+        return error.code;
+    }
+    return undefined;
+};
 export const getMessageFromUnknownError = (error) => {
     let message = 'An unknown error has occurred.';
     if (error instanceof AxiosError) {

package/dist/utils/user-config.js

@@ -1,11 +1,38 @@
+import { getCodeFromUnknownError, UserError } from '../utils/error.js';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
 import { readUser, writeUser } from 'rc9';
 class UserConfigImpl {
     file = '.capawesome';
     read() {
-        return readUser({ name: this.file });
+        try {
+            return readUser({ name: this.file });
+        }
+        catch (error) {
+            this.rethrow(error);
+        }
     }
     write(config) {
-        writeUser(config, { name: this.file });
+        try {
+            writeUser(config, { name: this.file });
+        }
+        catch (error) {
+            this.rethrow(error);
+        }
+    }
+    rethrow(error) {
+        const code = getCodeFromUnknownError(error);
+        if (code === 'EACCES' || code === 'EPERM') {
+            const path = error instanceof Error && 'path' in error && typeof error.path === 'string'
+                ? error.path
+                : this.getResolvedPath();
+            throw new UserError(`Permission denied accessing ${path}. The file may be owned by another user (e.g. from a previous run with sudo). ` +
+                `Try running \`sudo chown $USER ${path}\` or \`rm ${path}\`, then retry.`);
+        }
+        throw error;
+    }
+    getResolvedPath() {
+        return resolve(process.env.XDG_CONFIG_HOME || homedir(), this.file);
     }
 }
 const userConfig = new UserConfigImpl();

package/dist/utils/user-config.test.js

@@ -0,0 +1,93 @@
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { readUser, writeUser } from 'rc9';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { UserError } from './error.js';
+import userConfig from './user-config.js';
+vi.mock('rc9');
+describe('userConfig', () => {
+    const mockReadUser = vi.mocked(readUser);
+    const mockWriteUser = vi.mocked(writeUser);
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    const createFsError = (code, path) => Object.assign(new Error(code), { code, path });
+    describe('read', () => {
+        it('should return the config on success', () => {
+            mockReadUser.mockReturnValue({ token: 'abc' });
+            expect(userConfig.read()).toEqual({ token: 'abc' });
+        });
+        it('should throw UserError on EACCES with the failing path in the message', () => {
+            const error = createFsError('EACCES', '/home/user/.capawesome');
+            mockReadUser.mockImplementation(() => {
+                throw error;
+            });
+            expect(() => userConfig.read()).toThrow(UserError);
+            expect(() => userConfig.read()).toThrow(/\/home\/user\/\.capawesome/);
+        });
+        it('should throw UserError on EPERM', () => {
+            const error = createFsError('EPERM', '/home/user/.capawesome');
+            mockReadUser.mockImplementation(() => {
+                throw error;
+            });
+            expect(() => userConfig.read()).toThrow(UserError);
+        });
+        it('should fall back to the resolved home path when the error has no path', () => {
+            const error = Object.assign(new Error('EACCES'), { code: 'EACCES' });
+            mockReadUser.mockImplementation(() => {
+                throw error;
+            });
+            const expectedPath = resolve(process.env.XDG_CONFIG_HOME || homedir(), '.capawesome');
+            expect(() => userConfig.read()).toThrow(expectedPath);
+        });
+        it('should rethrow non-access errors as-is', () => {
+            const error = new Error('something else');
+            mockReadUser.mockImplementation(() => {
+                throw error;
+            });
+            let caught;
+            try {
+                userConfig.read();
+            }
+            catch (e) {
+                caught = e;
+            }
+            expect(caught).toBe(error);
+        });
+    });
+    describe('write', () => {
+        it('should call writeUser on success', () => {
+            userConfig.write({ token: 'abc' });
+            expect(mockWriteUser).toHaveBeenCalledWith({ token: 'abc' }, { name: '.capawesome' });
+        });
+        it('should throw UserError on EACCES with the failing path in the message', () => {
+            const error = createFsError('EACCES', '/home/user/.capawesome');
+            mockWriteUser.mockImplementation(() => {
+                throw error;
+            });
+            expect(() => userConfig.write({})).toThrow(UserError);
+            expect(() => userConfig.write({})).toThrow(/\/home\/user\/\.capawesome/);
+        });
+        it('should throw UserError on EPERM', () => {
+            const error = createFsError('EPERM', '/home/user/.capawesome');
+            mockWriteUser.mockImplementation(() => {
+                throw error;
+            });
+            expect(() => userConfig.write({})).toThrow(UserError);
+        });
+        it('should rethrow non-access errors as-is', () => {
+            const error = new Error('something else');
+            mockWriteUser.mockImplementation(() => {
+                throw error;
+            });
+            let caught;
+            try {
+                userConfig.write({});
+            }
+            catch (e) {
+                caught = e;
+            }
+            expect(caught).toBe(error);
+        });
+    });
+});

package/package.json

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