faces-cli 1.5.15 → 1.6.0

package/dist/client.d.ts

@@ -1,6 +1,15 @@
 export declare class FacesAPIError extends Error {
     statusCode: number;
-    constructor(statusCode: number, message: string);
+    errorCode?: string;
+    fallbackAvailable?: boolean;
+    constructor(statusCode: number, message: string, opts?: {
+        errorCode?: string;
+        fallbackAvailable?: boolean;
+    });
+}
+export interface ResponseWithHeaders<T = unknown> {
+    data: T;
+    headers: Record<string, string>;
 }
 export declare class FacesClient {
     private baseUrl;
@@ -19,6 +28,10 @@ export declare class FacesClient {
         requireJwt?: boolean;
         body?: unknown;
     }): Promise<unknown>;
+    postWithHeaders(path: string, opts?: {
+        requireJwt?: boolean;
+        body?: unknown;
+    }): Promise<ResponseWithHeaders>;
     postNoAuth(path: string, body: unknown): Promise<unknown>;
     patch(path: string, opts?: {
         requireJwt?: boolean;

package/dist/client.js

@@ -1,9 +1,13 @@
 export class FacesAPIError extends Error {
     statusCode;
-    constructor(statusCode, message) {
+    errorCode;
+    fallbackAvailable;
+    constructor(statusCode, message, opts) {
         super(message);
         this.statusCode = statusCode;
         this.name = 'FacesAPIError';
+        this.errorCode = opts?.errorCode;
+        this.fallbackAvailable = opts?.fallbackAvailable;
     }
 }
 export class FacesClient {
@@ -40,14 +44,24 @@ export class FacesClient {
     }
     async parseError(resp) {
         let msg = resp.statusText;
+        let errorCode;
+        let fallbackAvailable;
         try {
             const body = await resp.json();
-            const raw = body.detail ?? body.error ?? body.message ?? msg;
-            if (typeof raw === 'object' && raw !== null && 'message' in raw) {
-                msg = String(raw.message);
+            // Structured OAuth rejection (422)
+            if (body.error === 'oauth_rejected') {
+                errorCode = 'oauth_rejected';
+                fallbackAvailable = body.fallback_available;
+                msg = String(body.detail ?? 'OAuth request rejected');
             }
             else {
-                msg = typeof raw === 'object' ? JSON.stringify(raw) : String(raw);
+                const raw = body.detail ?? body.error ?? body.message ?? msg;
+                if (typeof raw === 'object' && raw !== null && 'message' in raw) {
+                    msg = String(raw.message);
+                }
+                else {
+                    msg = typeof raw === 'object' ? JSON.stringify(raw) : String(raw);
+                }
             }
         }
         catch {
@@ -57,7 +71,7 @@ export class FacesClient {
             msg = `Payment required: ${msg}`;
         if (resp.status === 403)
             msg = `Forbidden: ${msg}`;
-        return new FacesAPIError(resp.status, msg);
+        return new FacesAPIError(resp.status, msg, { errorCode, fallbackAvailable });
     }
     async get(path, opts = {}) {
         let url = this.url(path);
@@ -91,6 +105,26 @@ export class FacesClient {
             throw await this.parseError(resp);
         return resp.json();
     }
+    async postWithHeaders(path, opts = {}) {
+        let resp;
+        try {
+            resp = await fetch(this.url(path), {
+                method: 'POST',
+                headers: { ...this.authHeader(opts.requireJwt), 'Content-Type': 'application/json' },
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            });
+        }
+        catch (err) {
+            this.wrapNetworkError(err, path);
+        }
+        if (!resp.ok)
+            throw await this.parseError(resp);
+        const headers = {};
+        for (const [k, v] of resp.headers.entries())
+            headers[k] = v;
+        const data = await resp.json();
+        return { data, headers };
+    }
     async postNoAuth(path, body) {
         let resp;
         try {

package/dist/commands/account/preferences.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base.js';
+export default class AccountPreferences extends BaseCommand {
+    static description: string;
+    static flags: {
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        key: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+        value: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static examples: string[];
+    run(): Promise<unknown>;
+}

package/dist/commands/account/preferences.js

@@ -0,0 +1,65 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class AccountPreferences extends BaseCommand {
+    static description = 'View or update account preferences (api_fallback, default_model)';
+    static flags = {
+        ...BaseCommand.baseFlags,
+    };
+    static args = {
+        key: Args.string({ description: 'Preference key to update (api_fallback, default_model)' }),
+        value: Args.string({ description: 'New value' }),
+    };
+    static examples = [
+        'faces account:preferences',
+        'faces account:preferences default_model gpt-5.4',
+        'faces account:preferences api_fallback true',
+    ];
+    async run() {
+        const { args, flags } = await this.parse(AccountPreferences);
+        const client = this.makeClient(flags);
+        // If no key provided, show current preferences
+        if (!args.key) {
+            let data;
+            try {
+                data = await client.get('/v1/user/preferences');
+            }
+            catch (err) {
+                if (err instanceof FacesAPIError)
+                    this.error(`Error (${err.statusCode}): ${err.message}`);
+                throw err;
+            }
+            if (!this.jsonEnabled())
+                this.printHuman(data);
+            return data;
+        }
+        // Update a preference
+        if (!args.value)
+            this.error('Provide a value to set.');
+        const validKeys = ['api_fallback', 'default_model'];
+        if (!validKeys.includes(args.key)) {
+            this.error(`Unknown preference '${args.key}'. Valid keys: ${validKeys.join(', ')}`);
+        }
+        let parsedValue = args.value;
+        if (args.key === 'api_fallback') {
+            if (args.value !== 'true' && args.value !== 'false') {
+                this.error('api_fallback must be "true" or "false"');
+            }
+            parsedValue = args.value === 'true';
+        }
+        let data;
+        try {
+            data = await client.patch('/v1/user/preferences', { body: { [args.key]: parsedValue } });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (!this.jsonEnabled()) {
+            this.log(`Set ${args.key} = ${args.value}`);
+            this.printHuman(data);
+        }
+        return data;
+    }
+}

package/dist/commands/chat/chat.d.ts

@@ -10,6 +10,7 @@ export default class ChatChat extends BaseCommand {
         temperature: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         responses: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -21,4 +22,5 @@ export default class ChatChat extends BaseCommand {
     private runChatCompletions;
     private runMessages;
     private runResponses;
+    private extractText;
 }

package/dist/commands/chat/chat.js

@@ -20,6 +20,7 @@ export default class ChatChat extends BaseCommand {
         temperature: Flags.string({ description: 'Temperature (0.0-2.0)' }),
         file: Flags.string({ description: 'Read message from file' }),
         responses: Flags.boolean({ description: 'Use OpenAI Responses API instead of Chat Completions', default: false }),
+        'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
         face_username: Args.string({ description: 'Face alias (or alias@model)', required: true }),
@@ -64,8 +65,15 @@ export default class ChatChat extends BaseCommand {
             }
         }
         catch (err) {
-            if (err instanceof FacesAPIError)
+            if (err instanceof FacesAPIError) {
+                if (err.errorCode === 'oauth_rejected') {
+                    const hint = err.fallbackAvailable
+                        ? 'Run `faces account:preferences api_fallback true` to allow paid fallback.'
+                        : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.';
+                    this.error(`OAuth failed: ${err.message}\n${hint}`);
+                }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
             throw err;
         }
     }
@@ -80,6 +88,8 @@ export default class ChatChat extends BaseCommand {
             payload.max_tokens = flags['max-tokens'];
         if (flags.temperature !== undefined)
             payload.temperature = Number.parseFloat(flags.temperature);
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
         if (flags.stream) {
             for await (const line of client.stream('/v1/chat/completions', payload)) {
                 if (!line.startsWith('data: '))
@@ -99,13 +109,25 @@ export default class ChatChat extends BaseCommand {
             process.stdout.write('\n');
             return {};
         }
-        const data = (await client.post('/v1/chat/completions', { body: payload }));
-        if (this.jsonEnabled())
-            return data;
-        const choices = data.choices;
-        const message = choices?.[0]?.message;
-        this.log(String(message?.content ?? ''));
-        return data;
+        const { data, headers } = await client.postWithHeaders('/v1/chat/completions', { body: payload });
+        const body = data;
+        const routedEndpoint = headers['x-faces-routed-endpoint'];
+        // Extract text based on which format the backend used
+        const text = this.extractText(body, routedEndpoint);
+        if (this.jsonEnabled()) {
+            const meta = {};
+            if (headers['x-faces-provider'])
+                meta.provider = headers['x-faces-provider'];
+            if (headers['x-faces-cost-usd'])
+                meta.cost_usd = headers['x-faces-cost-usd'];
+            if (routedEndpoint)
+                meta.routed_endpoint = routedEndpoint;
+            if (Object.keys(meta).length > 0)
+                body._meta = meta;
+            return body;
+        }
+        this.log(text);
+        return body;
     }
     async runMessages(client, model, userMessages, flags) {
         const msgs = userMessages.map((m) => ({ role: 'user', content: m }));
@@ -117,6 +139,8 @@ export default class ChatChat extends BaseCommand {
         };
         if (flags.system)
             payload.system = flags.system;
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
         if (flags.stream) {
             for await (const line of client.stream('/v1/messages', payload)) {
                 if (!line.startsWith('data: '))
@@ -137,21 +161,32 @@ export default class ChatChat extends BaseCommand {
             process.stdout.write('\n');
             return {};
         }
-        const data = (await client.post('/v1/messages', { body: payload }));
-        if (this.jsonEnabled())
-            return data;
+        const { data, headers } = await client.postWithHeaders('/v1/messages', { body: payload });
+        const body = data;
+        if (this.jsonEnabled()) {
+            const meta = {};
+            if (headers['x-faces-provider'])
+                meta.provider = headers['x-faces-provider'];
+            if (headers['x-faces-cost-usd'])
+                meta.cost_usd = headers['x-faces-cost-usd'];
+            if (Object.keys(meta).length > 0)
+                body._meta = meta;
+            return body;
+        }
         let content = '';
-        for (const block of data.content ?? []) {
+        for (const block of body.content ?? []) {
             if (block.type === 'text')
                 content += String(block.text ?? '');
         }
         this.log(content);
-        return data;
+        return body;
     }
     async runResponses(client, model, input, flags) {
         const payload = { model, input, stream: flags.stream };
         if (flags.system)
             payload.instructions = flags.system;
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
         if (flags.stream) {
             for await (const line of client.stream('/v1/responses', payload)) {
                 if (!line.startsWith('data: '))
@@ -172,17 +207,52 @@ export default class ChatChat extends BaseCommand {
             process.stdout.write('\n');
             return {};
         }
-        const data = (await client.post('/v1/responses', { body: payload }));
-        if (this.jsonEnabled())
-            return data;
+        const { data, headers } = await client.postWithHeaders('/v1/responses', { body: payload });
+        const body = data;
+        if (this.jsonEnabled()) {
+            const meta = {};
+            if (headers['x-faces-provider'])
+                meta.provider = headers['x-faces-provider'];
+            if (headers['x-faces-cost-usd'])
+                meta.cost_usd = headers['x-faces-cost-usd'];
+            if (Object.keys(meta).length > 0)
+                body._meta = meta;
+            return body;
+        }
         let outputText = '';
-        for (const item of data.output ?? []) {
+        for (const item of body.output ?? []) {
             for (const block of item.content ?? []) {
                 if (block.type === 'output_text')
                     outputText += String(block.text ?? '');
             }
         }
         this.log(outputText);
-        return data;
+        return body;
+    }
+    extractText(body, routedEndpoint) {
+        if (routedEndpoint === '/v1/responses') {
+            // OpenAI Responses format
+            let text = '';
+            for (const item of body.output ?? []) {
+                for (const block of item.content ?? []) {
+                    if (block.type === 'output_text')
+                        text += String(block.text ?? '');
+                }
+            }
+            return text;
+        }
+        if (routedEndpoint === '/v1/messages') {
+            // Anthropic Messages format
+            let text = '';
+            for (const block of body.content ?? []) {
+                if (block.type === 'text')
+                    text += String(block.text ?? '');
+            }
+            return text;
+        }
+        // Standard chat/completions format (default)
+        const choices = body.choices;
+        const message = choices?.[0]?.message;
+        return String(message?.content ?? '');
     }
 }

package/dist/commands/chat/messages.d.ts

@@ -6,6 +6,7 @@ export default class ChatMessages extends BaseCommand {
         system: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         stream: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'max-tokens': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/chat/messages.js

@@ -9,6 +9,7 @@ export default class ChatMessages extends BaseCommand {
         system: Flags.string({ description: 'System prompt' }),
         stream: Flags.boolean({ description: 'Stream the response', default: false }),
         'max-tokens': Flags.integer({ description: 'Max tokens', default: 1024 }),
+        'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
         face_model: Args.string({ description: 'Face model (e.g. myface or myface@claude-sonnet-4-6)', required: true }),
@@ -25,6 +26,8 @@ export default class ChatMessages extends BaseCommand {
         };
         if (flags.system)
             payload.system = flags.system;
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
         try {
             if (flags.stream) {
                 for await (const line of client.stream('/v1/messages', payload)) {
@@ -48,20 +51,36 @@ export default class ChatMessages extends BaseCommand {
                 process.stdout.write('\n');
                 return {};
             }
-            const data = (await client.post('/v1/messages', { body: payload }));
-            if (this.jsonEnabled())
-                return data;
+            const { data, headers } = await client.postWithHeaders('/v1/messages', { body: payload });
+            const body = data;
+            if (this.jsonEnabled()) {
+                const meta = {};
+                if (headers['x-faces-provider'])
+                    meta.provider = headers['x-faces-provider'];
+                if (headers['x-faces-cost-usd'])
+                    meta.cost_usd = headers['x-faces-cost-usd'];
+                if (Object.keys(meta).length > 0)
+                    body._meta = meta;
+                return body;
+            }
             let content = '';
-            for (const block of data.content ?? []) {
+            for (const block of body.content ?? []) {
                 if (block.type === 'text')
                     content += String(block.text ?? '');
             }
             this.log(content);
-            return data;
+            return body;
         }
         catch (err) {
-            if (err instanceof FacesAPIError)
+            if (err instanceof FacesAPIError) {
+                if (err.errorCode === 'oauth_rejected') {
+                    const hint = err.fallbackAvailable
+                        ? 'Run `faces account:preferences api_fallback true` to allow paid fallback.'
+                        : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.';
+                    this.error(`OAuth failed: ${err.message}\n${hint}`);
+                }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
             throw err;
         }
     }

package/dist/commands/chat/responses.d.ts

@@ -5,6 +5,7 @@ export default class ChatResponses extends BaseCommand {
         message: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         instructions: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         stream: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/chat/responses.js

@@ -8,6 +8,7 @@ export default class ChatResponses extends BaseCommand {
         message: Flags.string({ char: 'm', description: 'User input message', required: true }),
         instructions: Flags.string({ description: 'System instructions' }),
         stream: Flags.boolean({ description: 'Stream the response', default: false }),
+        'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
         face_model: Args.string({ description: 'Face model (e.g. myface or myface@gpt-4o)', required: true }),
@@ -22,6 +23,8 @@ export default class ChatResponses extends BaseCommand {
         };
         if (flags.instructions)
             payload.instructions = flags.instructions;
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
         try {
             if (flags.stream) {
                 for await (const line of client.stream('/v1/responses', payload)) {
@@ -45,22 +48,38 @@ export default class ChatResponses extends BaseCommand {
                 process.stdout.write('\n');
                 return {};
             }
-            const data = (await client.post('/v1/responses', { body: payload }));
-            if (this.jsonEnabled())
-                return data;
+            const { data, headers } = await client.postWithHeaders('/v1/responses', { body: payload });
+            const body = data;
+            if (this.jsonEnabled()) {
+                const meta = {};
+                if (headers['x-faces-provider'])
+                    meta.provider = headers['x-faces-provider'];
+                if (headers['x-faces-cost-usd'])
+                    meta.cost_usd = headers['x-faces-cost-usd'];
+                if (Object.keys(meta).length > 0)
+                    body._meta = meta;
+                return body;
+            }
             let outputText = '';
-            for (const item of data.output ?? []) {
+            for (const item of body.output ?? []) {
                 for (const block of item.content ?? []) {
                     if (block.type === 'output_text')
                         outputText += String(block.text ?? '');
                 }
             }
             this.log(outputText);
-            return data;
+            return body;
         }
         catch (err) {
-            if (err instanceof FacesAPIError)
+            if (err instanceof FacesAPIError) {
+                if (err.errorCode === 'oauth_rejected') {
+                    const hint = err.fallbackAvailable
+                        ? 'Run `faces account:preferences api_fallback true` to allow paid fallback.'
+                        : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.';
+                    this.error(`OAuth failed: ${err.message}\n${hint}`);
+                }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
             throw err;
         }
     }

package/dist/commands/compile/thread/create.d.ts

@@ -3,6 +3,7 @@ export default class CompileThreadCreate extends BaseCommand {
     static description: string;
     static flags: {
         label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/compile/thread/create.js

@@ -6,6 +6,7 @@ export default class CompileThreadCreate extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         label: Flags.string({ description: 'Thread label' }),
+        'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
         face_id: Args.string({ description: 'Face alias', required: true }),
@@ -16,13 +17,22 @@ export default class CompileThreadCreate extends BaseCommand {
         const payload = { alias: args.face_id };
         if (flags.label)
             payload.label = flags.label;
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
         let data;
         try {
             data = await client.post('/v1/compile/threads', { body: payload });
         }
         catch (err) {
-            if (err instanceof FacesAPIError)
+            if (err instanceof FacesAPIError) {
+                if (err.errorCode === 'oauth_rejected') {
+                    const hint = err.fallbackAvailable
+                        ? 'Run `faces account:preferences api_fallback true` to allow paid fallback.'
+                        : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.';
+                    this.error(`OAuth failed: ${err.message}\n${hint}`);
+                }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
             throw err;
         }
         if (!this.jsonEnabled())

package/dist/commands/compile/thread/message.d.ts

@@ -3,6 +3,7 @@ export default class CompileThreadMessage extends BaseCommand {
     static description: string;
     static flags: {
         message: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/compile/thread/message.js

@@ -6,6 +6,7 @@ export default class CompileThreadMessage extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         message: Flags.string({ char: 'm', description: 'User message to append', required: true }),
+        'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
         thread_id: Args.string({ description: 'Thread ID', required: true }),
@@ -13,15 +14,25 @@ export default class CompileThreadMessage extends BaseCommand {
     async run() {
         const { args, flags } = await this.parse(CompileThreadMessage);
         const client = this.makeClient(flags);
+        const payload = { message: flags.message };
+        if (flags['oauth-only'])
+            payload.oauth_only = true;
         let data;
         try {
             data = await client.post(`/v1/compile/threads/${args.thread_id}/messages`, {
-                body: { message: flags.message },
+                body: payload,
             });
         }
         catch (err) {
-            if (err instanceof FacesAPIError)
+            if (err instanceof FacesAPIError) {
+                if (err.errorCode === 'oauth_rejected') {
+                    const hint = err.fallbackAvailable
+                        ? 'Run `faces account:preferences api_fallback true` to allow paid fallback.'
+                        : 'Run `faces billing:topup` to add credits, then enable fallback with `faces account:preferences api_fallback true`.';
+                    this.error(`OAuth failed: ${err.message}\n${hint}`);
+                }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
             throw err;
         }
         if (!this.jsonEnabled())