@aderis-erp/cli 1.0.14 → 1.0.15

package/dist/commands/vendor-invoices.js

@@ -1,6 +1,6 @@
 import { Command, Args, Flags } from '@oclif/core';
 import { apiRequest, ApiError, normalizeSortBy } from '../lib/api-client.js';
-import { getCurrentContext, getContext, getBaseUrls } from '../lib/config.js';
+import { getCurrentContext, getContext, getBaseUrls, hasCredentials, missingCredentialsMessage } from '../lib/config.js';
 // Add 'import' action if both create and update exist
 const HAS_IMPORT = true;
 const HAS_EXPORT = true;
@@ -9,12 +9,12 @@ const NESTED_IMPORTS = ["line-items", "notes", "files", "payments"];
 const SUBCOMMANDS = [...["list", "create", "get", "update", "delete", "submit", "approve", "decline", "book", "rebuild-journal", "cancel", "confirm-cancellation", "change-vendor", "recalculate-payment-status", "validate", "create-line-items", "update-line-items", "delete-line-items", "list-notes", "create-notes", "get-notes", "update-notes", "delete-notes", "list-files", "create-files", "get-files", "update-files", "delete-files", "files-download", "list-payments", "create-payments", "get-payments", "update-payments", "delete-payments", "payments-approve", "payments-cancel"], ...(HAS_IMPORT ? ['import'] : []), ...(HAS_EXPORT ? ['export'] : []), ...NESTED_IMPORTS.map(n => `import-${n}`)];
 const ENDPOINTS = {
     'list': { method: 'GET', path: '/v1/vendor-invoices', summary: 'Get all vendor invoices with pagination', pathParams: [], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
-    'create': { method: 'POST', path: '/v1/vendor-invoices', summary: 'Create a new vendor invoice', pathParams: [], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: ['earlyPaymentDiscounts', 'totalAmountByTaxRate', 'files', 'notes', 'lineItems', 'tagIds', 'payments'] },
+    'create': { method: 'POST', path: '/v1/vendor-invoices', summary: 'Create a new vendor invoice', pathParams: [], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: ['earlyPaymentDiscounts', 'totalAmountByTaxRate', 'files', 'notes', 'lineItems', 'tagIds', 'tagCodes', 'payments'] },
     'get': { method: 'GET', path: '/v1/vendor-invoices/{id}', summary: 'Get a vendor invoice by ID', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
-    'update': { method: 'PATCH', path: '/v1/vendor-invoices/{id}', summary: 'Update a vendor invoice', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: ['earlyPaymentDiscounts', 'totalAmountByTaxRate', 'files', 'notes', 'lineItems', 'tagIds', 'removeFileIds'] },
+    'update': { method: 'PATCH', path: '/v1/vendor-invoices/{id}', summary: 'Update a vendor invoice', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: ['earlyPaymentDiscounts', 'totalAmountByTaxRate', 'files', 'notes', 'lineItems', 'tagIds', 'tagCodes', 'removeFileIds'] },
     'delete': { method: 'DELETE', path: '/v1/vendor-invoices/{id}', summary: 'Delete a vendor invoice', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
     'submit': { method: 'POST', path: '/v1/vendor-invoices/{id}/submit', summary: 'Submit a vendor invoice for approval (transitions DRAFT to PENDING_APPROVAL)', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
-    'approve': { method: 'POST', path: '/v1/vendor-invoices/{id}/approve', summary: 'Approve a vendor invoice (transitions DRAFT/PENDING_APPROVAL to APPROVED)', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: ['earlyPaymentDiscounts', 'totalAmountByTaxRate', 'files', 'notes', 'lineItems', 'tagIds', 'removeFileIds'] },
+    'approve': { method: 'POST', path: '/v1/vendor-invoices/{id}/approve', summary: 'Approve a vendor invoice (transitions DRAFT/PENDING_APPROVAL to APPROVED)', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: ['earlyPaymentDiscounts', 'totalAmountByTaxRate', 'files', 'notes', 'lineItems', 'tagIds', 'tagCodes', 'removeFileIds'] },
     'decline': { method: 'POST', path: '/v1/vendor-invoices/{id}/decline', summary: 'Decline a vendor invoice (transitions PENDING_APPROVAL to DECLINED)', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
     'book': { method: 'POST', path: '/v1/vendor-invoices/{id}/book', summary: 'Manually book a vendor invoice (dispatch to ledger-booking-agent)', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
     'rebuild-journal': { method: 'POST', path: '/v1/vendor-invoices/{id}/rebuild-journal', summary: 'Rebuild a vendor invoice booking journal (dispatch to ledger-booking-agent)', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
@@ -22,7 +22,7 @@ const ENDPOINTS = {
     'confirm-cancellation': { method: 'POST', path: '/v1/vendor-invoices/{id}/confirm-cancellation', summary: 'Confirm bank cancellation for a vendor invoice (PENDING_CANCELLATION to CANCELLED)', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
     'change-vendor': { method: 'POST', path: '/v1/vendor-invoices/{id}/change-vendor', summary: 'Change the vendor on a vendor invoice', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
     'recalculate-payment-status': { method: 'POST', path: '/v1/vendor-invoices/{id}/recalculate-payment-status', summary: 'Recalculate a vendor invoice\'s open amount and payment status', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
-    'validate': { method: 'POST', path: '/v1/vendor-invoices/{id}/validate', summary: 'Validate a vendor invoice update without persisting changes', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: ['earlyPaymentDiscounts', 'totalAmountByTaxRate', 'files', 'notes', 'lineItems', 'tagIds', 'removeFileIds'] },
+    'validate': { method: 'POST', path: '/v1/vendor-invoices/{id}/validate', summary: 'Validate a vendor invoice update without persisting changes', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: ['earlyPaymentDiscounts', 'totalAmountByTaxRate', 'files', 'notes', 'lineItems', 'tagIds', 'tagCodes', 'removeFileIds'] },
     'create-line-items': { method: 'POST', path: '/v1/vendor-invoices/{invoiceId}/line-items', summary: 'Add a line item to a vendor invoice', pathParams: ['invoiceId'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
     'update-line-items': { method: 'PATCH', path: '/v1/vendor-invoices/{invoiceId}/line-items/{lineItemId}', summary: 'Update a line item on a vendor invoice', pathParams: ['invoiceId', 'lineItemId'], hasBody: true, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
     'delete-line-items': { method: 'DELETE', path: '/v1/vendor-invoices/{invoiceId}/line-items/{lineItemId}', summary: 'Remove a line item from a vendor invoice', pathParams: ['invoiceId', 'lineItemId'], hasBody: false, isMultipart: false, isBinaryResponse: false, bodyArrayFields: [] },
@@ -60,7 +60,7 @@ export default class VendorInvoices extends Command {
         id: Args.string({ description: 'Resource ID (for get, update, delete operations)', required: false }),
     };
     static flags = {
-        context: Flags.string({ char: 'c', description: 'Context to use' }),
+        context: Flags.string({ char: 'c', aliases: ['config'], env: 'ADERIS_CONTEXT', description: 'Context to use for this command, overriding the current context (alias: --config)' }),
         output: Flags.string({ char: 'o', description: 'Output format (default: table for import, json for other commands)', options: ['json', 'table', 'csv'] }),
         table: Flags.boolean({ char: 't', description: 'Output as table (shortcut for --output table)' }),
         csv: Flags.boolean({ description: 'Output as CSV (shortcut for --output csv)' }),
@@ -136,9 +136,9 @@ export default class VendorInvoices extends Command {
         }
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         const queryParams = {};
         if (flags.page)
             queryParams.page = flags.page;
@@ -381,9 +381,9 @@ export default class VendorInvoices extends Command {
     async runImport(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         // Get data from file, --data, or --set flags
         let items = [];
         if (flags.file) {
@@ -593,9 +593,9 @@ export default class VendorInvoices extends Command {
     async runExport(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         const listEndpoint = ENDPOINTS['list'];
         if (!listEndpoint)
             this.error('Export requires a list endpoint');
@@ -687,9 +687,9 @@ export default class VendorInvoices extends Command {
     async runCamt053Import(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         if (!flags.file) {
             this.error('CAMT.053 import requires --file (-f) flag with path to XML file');
         }
@@ -777,9 +777,9 @@ export default class VendorInvoices extends Command {
         }
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         // Get data from file, --data, or --set flags
         let items = [];
         if (flags.file) {

package/dist/commands/webhooks.js

@@ -1,6 +1,6 @@
 import { Command, Args, Flags } from '@oclif/core';
 import { apiRequest, ApiError, normalizeSortBy } from '../lib/api-client.js';
-import { getCurrentContext, getContext, getBaseUrls } from '../lib/config.js';
+import { getCurrentContext, getContext, getBaseUrls, hasCredentials, missingCredentialsMessage } from '../lib/config.js';
 // Add 'import' action if both create and update exist
 const HAS_IMPORT = true;
 const HAS_EXPORT = true;
@@ -31,7 +31,7 @@ export default class Webhooks extends Command {
         id: Args.string({ description: 'Resource ID (for get, update, delete operations)', required: false }),
     };
     static flags = {
-        context: Flags.string({ char: 'c', description: 'Context to use' }),
+        context: Flags.string({ char: 'c', aliases: ['config'], env: 'ADERIS_CONTEXT', description: 'Context to use for this command, overriding the current context (alias: --config)' }),
         output: Flags.string({ char: 'o', description: 'Output format (default: table for import, json for other commands)', options: ['json', 'table', 'csv'] }),
         table: Flags.boolean({ char: 't', description: 'Output as table (shortcut for --output table)' }),
         csv: Flags.boolean({ description: 'Output as CSV (shortcut for --output csv)' }),
@@ -103,9 +103,9 @@ export default class Webhooks extends Command {
         }
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         const queryParams = {};
         if (flags.page)
             queryParams.page = flags.page;
@@ -348,9 +348,9 @@ export default class Webhooks extends Command {
     async runImport(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         // Get data from file, --data, or --set flags
         let items = [];
         if (flags.file) {
@@ -560,9 +560,9 @@ export default class Webhooks extends Command {
     async runExport(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         const listEndpoint = ENDPOINTS['list'];
         if (!listEndpoint)
             this.error('Export requires a list endpoint');
@@ -654,9 +654,9 @@ export default class Webhooks extends Command {
     async runCamt053Import(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         if (!flags.file) {
             this.error('CAMT.053 import requires --file (-f) flag with path to XML file');
         }
@@ -744,9 +744,9 @@ export default class Webhooks extends Command {
         }
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         // Get data from file, --data, or --set flags
         let items = [];
         if (flags.file) {

package/dist/commands/workflows.js

@@ -1,6 +1,6 @@
 import { Command, Args, Flags } from '@oclif/core';
 import { apiRequest, ApiError, normalizeSortBy } from '../lib/api-client.js';
-import { getCurrentContext, getContext, getBaseUrls } from '../lib/config.js';
+import { getCurrentContext, getContext, getBaseUrls, hasCredentials, missingCredentialsMessage } from '../lib/config.js';
 // Add 'import' action if both create and update exist
 const HAS_IMPORT = false;
 const HAS_EXPORT = true;
@@ -23,7 +23,7 @@ export default class Workflows extends Command {
         id: Args.string({ description: 'Resource ID (for get, update, delete operations)', required: false }),
     };
     static flags = {
-        context: Flags.string({ char: 'c', description: 'Context to use' }),
+        context: Flags.string({ char: 'c', aliases: ['config'], env: 'ADERIS_CONTEXT', description: 'Context to use for this command, overriding the current context (alias: --config)' }),
         output: Flags.string({ char: 'o', description: 'Output format (default: table for import, json for other commands)', options: ['json', 'table', 'csv'] }),
         table: Flags.boolean({ char: 't', description: 'Output as table (shortcut for --output table)' }),
         csv: Flags.boolean({ description: 'Output as CSV (shortcut for --output csv)' }),
@@ -95,9 +95,9 @@ export default class Workflows extends Command {
         }
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         const queryParams = {};
         if (flags.page)
             queryParams.page = flags.page;
@@ -340,9 +340,9 @@ export default class Workflows extends Command {
     async runImport(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         // Get data from file, --data, or --set flags
         let items = [];
         if (flags.file) {
@@ -552,9 +552,9 @@ export default class Workflows extends Command {
     async runExport(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         const listEndpoint = ENDPOINTS['list'];
         if (!listEndpoint)
             this.error('Export requires a list endpoint');
@@ -646,9 +646,9 @@ export default class Workflows extends Command {
     async runCamt053Import(flags) {
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         if (!flags.file) {
             this.error('CAMT.053 import requires --file (-f) flag with path to XML file');
         }
@@ -736,9 +736,9 @@ export default class Workflows extends Command {
         }
         const context = flags.context ? getContext(flags.context) : getCurrentContext();
         if (!context)
-            this.error('No context configured. Run: aderis auth login --new');
-        if (!context.tokens)
-            this.error('Not logged in. Run: aderis auth login');
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
         // Get data from file, --data, or --set flags
         let items = [];
         if (flags.file) {

package/dist/lib/api-client.js

@@ -1,6 +1,6 @@
 import axios from 'axios';
-import { getValidToken } from './auth.js';
-import { getBaseUrls, getCurrentContext } from './config.js';
+import { getAuthHeaders } from './auth.js';
+import { getAuthType, getBaseUrls, getCurrentContext } from './config.js';
 /**
  * Normalize a --sort-by value: comma-separated fields, each optionally suffixed
  * with `:ASC` or `:DESC`. Fields without an explicit direction default to DESC
@@ -39,14 +39,15 @@ export async function createApiClient(contextName, options = false) {
     if (!context) {
         throw new Error('No context configured. Run: aderis auth login --new');
     }
-    const token = await getValidToken(context.name);
+    const authHeaders = await getAuthHeaders(context.name);
     const { api: baseURL } = getBaseUrls(context.environment);
     const client = axios.create({
         baseURL,
         headers: {
             Accept: binary ? '*/*' : (acceptAny ? '*/*' : 'application/json'),
-            Authorization: `Bearer ${token}`,
             'Content-Type': 'application/json',
+            // Either `Authorization: Bearer <token>` or `x-api-key: <key>`.
+            ...authHeaders,
         },
         // Serialize arrays as repeated params (key=v1&key=v2) instead of bracket format (key[]=v1)
         paramsSerializer: { indexes: null },
@@ -56,9 +57,13 @@ export async function createApiClient(contextName, options = false) {
     // Response interceptor for error handling
     client.interceptors.response.use((response) => response, (error) => {
         if (error.response) {
-            // Handle 401 with a clear message
+            // Handle 401 with a clear message, pointing at the right remedy for the
+            // context's auth type — re-login only helps OAuth contexts.
             if (error.response.status === 401) {
-                throw new ApiError('Session expired. Please run: aderis auth login', 401, error.response.data);
+                const message = getAuthType(context) === 'api_key'
+                    ? `API key for context "${context.name}" was rejected. Check the key with: aderis config set-api-key --context ${context.name}`
+                    : 'Session expired. Please run: aderis auth login';
+                throw new ApiError(message, 401, error.response.data);
             }
             const message = extractErrorMessage(error.response.data);
             throw new ApiError(message, error.response.status, error.response.data);

package/dist/lib/auth.d.ts

@@ -4,6 +4,14 @@ export declare function login(context: Context, options?: {
 }): Promise<TokenData>;
 export declare function refreshTokens(contextName: string): Promise<TokenData>;
 export declare function getValidToken(contextName: string): Promise<string>;
+/**
+ * Build the auth headers for a context: a bearer token for `oauth2` contexts
+ * (refreshing it first if needed) or `x-api-key` for `api_key` contexts.
+ *
+ * This is the single place that decides how credentials reach the API — callers
+ * should never read `tokens` or `api_key` off a context to build headers.
+ */
+export declare function getAuthHeaders(contextName: string): Promise<Record<string, string>>;
 export declare function testAuth(contextName: string): Promise<{
     email: string;
     name?: string;

package/dist/lib/auth.js

@@ -4,7 +4,7 @@ import * as crypto from 'node:crypto';
 import * as http from 'node:http';
 import { URL, URLSearchParams } from 'node:url';
 import open from 'open';
-import { getBaseUrls, getContext, saveCachedTenants, saveTokens, } from './config.js';
+import { getAuthType, getBaseUrls, getContext, missingCredentialsMessage, saveCachedTenants, saveTokens, } from './config.js';
 function buildValidatedUrl(baseUrl, path) {
     try {
         // Minimal path validation
@@ -132,6 +132,23 @@ function renderAuthPage(type, title, message) {
 </body>
 </html>`;
 }
+/**
+ * Guard for flows that only exist for OAuth contexts (browser login, token
+ * refresh, Frontegg tenant switching). API keys are issued per tenant, so there
+ * is nothing to log into or switch.
+ */
+function requireOAuthContext(context, action) {
+    if (getAuthType(context) === 'api_key') {
+        throw new Error(`${action} requires OAuth. Context "${context.name}" authenticates with an API key, which is already scoped to one tenant.`);
+    }
+}
+/** `client_id` is optional on Context (API-key contexts have none), so OAuth flows must assert it. */
+function requireClientId(context) {
+    if (!context.client_id) {
+        throw new Error(`Context "${context.name}" has no OAuth client ID. Recreate it with: aderis config add`);
+    }
+    return context.client_id;
+}
 function generatePKCE() {
     const verifier = crypto.randomBytes(32).toString('base64url');
     const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
@@ -143,7 +160,7 @@ function generateState() {
 function buildAuthorizeUrl(context, pkce, state, options = {}) {
     const { auth: authUrl } = getBaseUrls(context.environment);
     const url = new URL(`${authUrl}/oauth/authorize`);
-    url.searchParams.set('client_id', context.client_id);
+    url.searchParams.set('client_id', requireClientId(context));
     url.searchParams.set('redirect_uri', REDIRECT_URI);
     url.searchParams.set('response_type', 'code');
     url.searchParams.set('state', state);
@@ -155,6 +172,7 @@ function buildAuthorizeUrl(context, pkce, state, options = {}) {
     return url.toString();
 }
 export async function login(context, options = {}) {
+    requireOAuthContext(context, 'Browser login');
     const pkce = generatePKCE();
     const state = generateState();
     const authorizationUrl = buildAuthorizeUrl(context, pkce, state, options);
@@ -252,7 +270,7 @@ async function exchangeCodeForTokens(context, code, codeVerifier) {
     const { auth: authUrl } = getBaseUrls(context.environment);
     const params = new URLSearchParams();
     params.set('grant_type', 'authorization_code');
-    params.set('client_id', context.client_id);
+    params.set('client_id', requireClientId(context));
     params.set('code', code);
     params.set('redirect_uri', REDIRECT_URI);
     params.set('code_verifier', codeVerifier);
@@ -279,13 +297,14 @@ export async function refreshTokens(contextName) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
+    requireOAuthContext(context, 'Token refresh');
     if (!context.tokens?.refresh_token) {
         throw new Error('No refresh token available. Please login again.');
     }
     const { auth: authUrl } = getBaseUrls(context.environment);
     const params = new URLSearchParams();
     params.set('grant_type', 'refresh_token');
-    params.set('client_id', context.client_id);
+    params.set('client_id', requireClientId(context));
     params.set('refresh_token', context.tokens.refresh_token);
     if (context.client_secret) {
         params.set('client_secret', context.client_secret);
@@ -321,6 +340,9 @@ export async function getValidToken(contextName) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
+    if (getAuthType(context) === 'api_key') {
+        throw new Error(`Context "${contextName}" authenticates with an API key and has no access token. Use getAuthHeaders() instead.`);
+    }
     if (!context.tokens?.access_token) {
         throw new Error('Not logged in. Please run: aderis auth login');
     }
@@ -334,17 +356,36 @@ export async function getValidToken(contextName) {
     }
     return context.tokens.access_token;
 }
+/**
+ * Build the auth headers for a context: a bearer token for `oauth2` contexts
+ * (refreshing it first if needed) or `x-api-key` for `api_key` contexts.
+ *
+ * This is the single place that decides how credentials reach the API — callers
+ * should never read `tokens` or `api_key` off a context to build headers.
+ */
+export async function getAuthHeaders(contextName) {
+    const context = getContext(contextName);
+    if (!context) {
+        throw new Error(`Context "${contextName}" not found`);
+    }
+    if (getAuthType(context) === 'api_key') {
+        if (!context.api_key) {
+            throw new Error(missingCredentialsMessage(context));
+        }
+        return { 'x-api-key': context.api_key };
+    }
+    return { Authorization: `Bearer ${await getValidToken(contextName)}` };
+}
 export async function testAuth(contextName) {
     const context = getContext(contextName);
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
-    const token = await getValidToken(contextName);
     const { api: apiUrl } = getBaseUrls(context.environment);
     const response = await axios.get(buildValidatedUrl(apiUrl, '/v1/auth/me'), {
         headers: {
             Accept: 'application/json',
-            Authorization: `Bearer ${token}`,
+            ...(await getAuthHeaders(contextName)),
         },
     });
     return response.data;
@@ -354,6 +395,7 @@ export async function listTenants(contextName) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
+    requireOAuthContext(context, 'Listing tenants');
     const token = await getValidToken(contextName);
     const { auth: authUrl } = getBaseUrls(context.environment);
     let response;
@@ -389,7 +431,8 @@ export async function getCurrentTenant(contextName) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
-    if (!context.tokens?.access_token) {
+    // API-key contexts carry no JWT, so there is no tenant to decode locally.
+    if (getAuthType(context) === 'api_key' || !context.tokens?.access_token) {
         return null;
     }
     const decoded = jwt.decode(context.tokens.access_token);
@@ -415,6 +458,7 @@ export async function switchTenant(contextName, tenantId) {
     if (!context) {
         throw new Error(`Context "${contextName}" not found`);
     }
+    requireOAuthContext(context, 'Switching tenants');
     if (!context.tokens?.refresh_token) {
         throw new Error('No refresh token available. Please login again.');
     }

package/dist/lib/base-api-command.js

@@ -1,11 +1,13 @@
 import { Command, Flags } from '@oclif/core';
 import { ApiError, apiRequest } from './api-client.js';
-import { getCurrentContext } from './config.js';
+import { getCurrentContext, hasCredentials, missingCredentialsMessage } from './config.js';
 export class BaseApiCommand extends Command {
     static globalFlags = {
         context: Flags.string({
+            aliases: ['config'],
             char: 'c',
-            description: 'Context to use (defaults to current context)',
+            description: 'Context to use, overriding the current context (alias: --config)',
+            env: 'ADERIS_CONTEXT',
         }),
         output: Flags.string({
             char: 'o',
@@ -66,8 +68,8 @@ export class BaseApiCommand extends Command {
         if (!context) {
             this.error('No context configured. Run: aderis auth login --new');
         }
-        if (!context.tokens) {
-            this.error(`Not logged in to context "${context.name}". Run: aderis auth login`);
+        if (!hasCredentials(context)) {
+            this.error(missingCredentialsMessage(context));
         }
     }
     printTable(data) {

package/dist/lib/config.d.ts

@@ -1,5 +1,15 @@
 import Conf from 'conf';
 export type Environment = 'dev' | 'live' | 'staging';
+/**
+ * How a context authenticates against the API.
+ *
+ * - `oauth2`: browser PKCE login, sends `Authorization: Bearer <access_token>`
+ * - `api_key`: a long-lived key, sends `x-api-key: <key>`
+ *
+ * Contexts created before API-key support have no `auth_type` field; they are
+ * treated as `oauth2`, so always read it through {@link getAuthType}.
+ */
+export type AuthType = 'api_key' | 'oauth2';
 export interface BaseUrls {
     api: string;
     auth: string;
@@ -17,8 +27,11 @@ export interface CachedTenant {
     tenantId: string;
 }
 export interface Context {
+    api_key?: string;
+    auth_type?: AuthType;
     cachedTenants?: CachedTenant[];
-    client_id: string;
+    /** Only required for `oauth2` contexts; API-key contexts have no OAuth client. */
+    client_id?: string;
     client_secret?: string;
     environment: Environment;
     name: string;
@@ -44,5 +57,22 @@ export declare function saveCachedTenants(contextName: string, tenants: CachedTe
 export declare function getCachedTenants(contextName: string): CachedTenant[] | undefined;
 export declare function getTokens(contextName: string): null | TokenData;
 export declare function clearTokens(contextName: string): void;
+export declare function saveApiKey(contextName: string, apiKey: string): void;
+export declare function clearApiKey(contextName: string): void;
+/**
+ * Auth type of a context, defaulting to `oauth2` for contexts stored before
+ * API-key support existed.
+ */
+export declare function getAuthType(context: Context): AuthType;
+/** Whether a context holds the credential its auth type needs to call the API. */
+export declare function hasCredentials(context: Context): boolean;
+/**
+ * The error to show when a context can't authenticate. Kept here so every
+ * command — including the ~60 generated ones — points at the right remedy for
+ * the context's auth type instead of always suggesting `auth login`.
+ */
+export declare function missingCredentialsMessage(context: Context): string;
+/** Redact a key for display: first and last 4 characters only. */
+export declare function maskApiKey(apiKey: string): string;
 export declare function getBaseUrls(environment: Environment): BaseUrls;
 export { config };

package/dist/lib/config.js

@@ -133,6 +133,37 @@ export function getTokens(contextName) {
 export function clearTokens(contextName) {
     updateContext(contextName, { tokens: undefined });
 }
+export function saveApiKey(contextName, apiKey) {
+    updateContext(contextName, { api_key: apiKey, auth_type: 'api_key' });
+}
+export function clearApiKey(contextName) {
+    updateContext(contextName, { api_key: undefined });
+}
+/**
+ * Auth type of a context, defaulting to `oauth2` for contexts stored before
+ * API-key support existed.
+ */
+export function getAuthType(context) {
+    return context.auth_type ?? 'oauth2';
+}
+/** Whether a context holds the credential its auth type needs to call the API. */
+export function hasCredentials(context) {
+    return getAuthType(context) === 'api_key' ? Boolean(context.api_key) : Boolean(context.tokens);
+}
+/**
+ * The error to show when a context can't authenticate. Kept here so every
+ * command — including the ~60 generated ones — points at the right remedy for
+ * the context's auth type instead of always suggesting `auth login`.
+ */
+export function missingCredentialsMessage(context) {
+    return getAuthType(context) === 'api_key'
+        ? `No API key set for context "${context.name}". Run: aderis config set-api-key --context ${context.name}`
+        : `Not logged in to context "${context.name}". Run: aderis auth login --context ${context.name}`;
+}
+/** Redact a key for display: first and last 4 characters only. */
+export function maskApiKey(apiKey) {
+    return apiKey.length <= 8 ? '*'.repeat(apiKey.length) : `${apiKey.slice(0, 4)}${'*'.repeat(8)}${apiKey.slice(-4)}`;
+}
 export function getBaseUrls(environment) {
     return BASE_URLS[environment];
 }