faces-cli 1.4.3 → 1.4.4

package/dist/catalog.d.ts

@@ -15,7 +15,7 @@ export interface FaceFrontmatter {
 }
 export interface FaceDataInput {
     name: string;
-    id: string;
+    alias: string;
     uid?: string;
     basic_facts?: Record<string, string | {
         value: string;

package/dist/catalog.js

@@ -82,7 +82,7 @@ export class CatalogService {
         if (!this.isEnabled())
             return;
         try {
-            const username = faceData.id;
+            const username = faceData.alias;
             const dir = path.join(CATALOG_DIR, username);
             fs.mkdirSync(dir, { recursive: true });
             const filePath = path.join(dir, 'FACE.md');

package/dist/client.js

@@ -21,16 +21,17 @@ export class FacesClient {
     authHeader(requireJwt = false) {
         if (requireJwt) {
             if (!this.token) {
-                process.stderr.write('Error: JWT login required. Run: faces auth login\n');
+                process.stderr.write('Error: JWT login required. Run: faces auth:login\n');
                 process.exit(1);
             }
             return { Authorization: `Bearer ${this.token}` };
         }
-        if (this.token)
-            return { Authorization: `Bearer ${this.token}` };
+        // API key takes priority over saved JWT (explicit key = deliberate choice)
         if (this.apiKey)
             return { Authorization: `Bearer ${this.apiKey}` };
-        process.stderr.write('Error: Authentication required. Run: faces auth login or set FACES_API_KEY\n');
+        if (this.token)
+            return { Authorization: `Bearer ${this.token}` };
+        process.stderr.write('Error: Authentication required. Run: faces auth:login or set FACES_API_KEY\n');
         process.exit(1);
     }
     wrapNetworkError(err, path) {

package/dist/commands/catalog/doctor.js

@@ -24,10 +24,10 @@ export default class CatalogDoctor extends BaseCommand {
             // List endpoint returns minimal fields; fetch full details for each
             remoteFaces = await Promise.all(arr.map(async (f) => {
                 try {
-                    return await client.get(`/v1/faces/${f.id}`);
+                    return await client.get(`/v1/faces/${f.alias}`);
                 }
                 catch {
-                    return { ...f, uid: f.id };
+                    return { ...f, uid: f.alias };
                 }
             }));
         }
@@ -36,20 +36,20 @@ export default class CatalogDoctor extends BaseCommand {
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        // Build map of remote faces by username
-        const remoteByUsername = new Map();
+        // Build map of remote faces by alias
+        const remoteByAlias = new Map();
         for (const f of remoteFaces) {
-            remoteByUsername.set(f.id, f);
+            remoteByAlias.set(f.alias, f);
         }
         // Read local catalog
-        const localUsernames = new Set();
+        const localAliases = new Set();
         const localFrontmatters = new Map();
         try {
             if (fs.existsSync(CATALOG_DIR)) {
                 for (const dirent of fs.readdirSync(CATALOG_DIR, { withFileTypes: true })) {
                     if (!dirent.isDirectory())
                         continue;
-                    localUsernames.add(dirent.name);
+                    localAliases.add(dirent.name);
                     const faceMdPath = path.join(CATALOG_DIR, dirent.name, 'FACE.md');
                     if (fs.existsSync(faceMdPath)) {
                         const content = fs.readFileSync(faceMdPath, 'utf8');
@@ -83,23 +83,23 @@ export default class CatalogDoctor extends BaseCommand {
         const stale = [];
         const noDescription = [];
         const orphaned = [];
-        for (const [username, remote] of remoteByUsername) {
-            if (!localUsernames.has(username)) {
+        for (const [alias, remote] of remoteByAlias) {
+            if (!localAliases.has(alias)) {
                 missing.push(remote);
             }
             else {
-                const local = localFrontmatters.get(username);
+                const local = localFrontmatters.get(alias);
                 if (local && local.name !== remote.name) {
                     stale.push(remote);
                 }
             }
-            const local = localFrontmatters.get(username);
+            const local = localFrontmatters.get(alias);
             if (!local?.description)
-                noDescription.push(username);
+                noDescription.push(alias);
         }
-        for (const username of localUsernames) {
-            if (!remoteByUsername.has(username))
-                orphaned.push(username);
+        for (const alias of localAliases) {
+            if (!remoteByAlias.has(alias))
+                orphaned.push(alias);
         }
         const doFix = flags.fix || flags.generate;
         if (!doFix) {
@@ -134,16 +134,16 @@ export default class CatalogDoctor extends BaseCommand {
             fixed++;
         }
         // Also refresh faces that exist but might have stale attributes
-        for (const [username, remote] of remoteByUsername) {
-            if (!missing.some((f) => f.id === username) && !stale.some((f) => f.id === username)) {
+        for (const [alias, remote] of remoteByAlias) {
+            if (!missing.some((f) => f.alias === alias) && !stale.some((f) => f.alias === alias)) {
                 // Face exists locally and name matches — still refresh attributes
                 catalog.writeFace(remote);
             }
         }
         // Remove orphans
         let removed = 0;
-        for (const username of orphaned) {
-            catalog.deleteFace(username);
+        for (const alias of orphaned) {
+            catalog.deleteFace(alias);
             removed++;
         }
         this.log(`Fixed ${fixed} catalog entries, removed ${removed} orphans.`);
@@ -153,13 +153,13 @@ export default class CatalogDoctor extends BaseCommand {
             const catalogModel = cfg.catalog_model ?? 'gpt-5-nano';
             this.log(`Generating descriptions for ${noDescription.length} face(s) via ${catalogModel}...`);
             let generated = 0;
-            for (const username of noDescription) {
-                const remote = remoteByUsername.get(username);
+            for (const alias of noDescription) {
+                const remote = remoteByAlias.get(alias);
                 if (!remote)
                     continue;
                 try {
                     const prompt = 'Describe yourself in one paragraph. Who are you, what do you care about, and what kind of questions are you best suited to answer?';
-                    const faceModel = `${username}@${catalogModel}`;
+                    const faceModel = `${alias}@${catalogModel}`;
                     const isAnthropic = catalogModel.startsWith('claude');
                     let text;
                     if (isAnthropic) {
@@ -177,15 +177,15 @@ export default class CatalogDoctor extends BaseCommand {
                     if (text) {
                         catalog.writeFace(remote, text.trim());
                         generated++;
-                        this.log(`  ${username}: done`);
+                        this.log(`  ${alias}: done`);
                     }
                     else {
-                        this.log(`  ${username}: no response`);
+                        this.log(`  ${alias}: no response`);
                     }
                 }
                 catch (err) {
                     const msg = err instanceof FacesAPIError ? `Error (${err.statusCode}): ${err.message}` : String(err);
-                    this.log(`  ${username}: failed — ${msg}`);
+                    this.log(`  ${alias}: failed — ${msg}`);
                 }
             }
             this.log(`Generated ${generated} description(s).`);

package/dist/commands/chat/chat.js

@@ -22,7 +22,7 @@ export default class ChatChat extends BaseCommand {
         responses: Flags.boolean({ description: 'Use OpenAI Responses API instead of Chat Completions', default: false }),
     };
     static args = {
-        face_username: Args.string({ description: 'Face username (or face@model)', required: true }),
+        face_username: Args.string({ description: 'Face alias (or alias@model)', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(ChatChat);

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

@@ -12,7 +12,7 @@ export default class CompileDocCreate extends BaseCommand {
         perspective: Flags.string({ description: 'Perspective (first-person or third-person)', options: ['first-person', 'third-person'], default: 'first-person' }),
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(CompileDocCreate);
@@ -25,7 +25,7 @@ export default class CompileDocCreate extends BaseCommand {
         }
         if (!content)
             this.error('Provide --content or --file.');
-        const payload = { model: args.face_id, content };
+        const payload = { alias: args.face_id, content };
         if (flags.label)
             payload.label = flags.label;
         if (flags.perspective)

package/dist/commands/compile/doc/index.js

@@ -18,7 +18,7 @@ export default class CompileDoc extends BaseCommand {
         timeout: Flags.integer({ description: 'Compile timeout in seconds (default: 600)', default: 600 }),
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(CompileDoc);
@@ -38,7 +38,7 @@ export default class CompileDoc extends BaseCommand {
             process.stderr.write('Creating document... ');
         let doc;
         try {
-            const payload = { model: args.face_id, content };
+            const payload = { alias: args.face_id, content };
             if (flags.label)
                 payload.label = flags.label;
             if (flags.perspective)

package/dist/commands/compile/doc/list.js

@@ -7,14 +7,14 @@ export default class CompileDocList extends BaseCommand {
         ...BaseCommand.baseFlags,
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(CompileDocList);
         const client = this.makeClient(flags);
         let data;
         try {
-            data = await client.get('/v1/compile/documents', { params: { model: args.face_id } });
+            data = await client.get('/v1/compile/documents', { params: { alias: args.face_id } });
         }
         catch (err) {
             if (err instanceof FacesAPIError)

package/dist/commands/compile/import.js

@@ -24,7 +24,7 @@ export default class CompileImport extends BaseCommand {
         }),
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(CompileImport);

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

@@ -8,12 +8,12 @@ export default class CompileThreadCreate extends BaseCommand {
         label: Flags.string({ description: 'Thread label' }),
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(CompileThreadCreate);
         const client = this.makeClient(flags);
-        const payload = { model: args.face_id };
+        const payload = { alias: args.face_id };
         if (flags.label)
             payload.label = flags.label;
         let data;

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

@@ -7,14 +7,14 @@ export default class CompileThreadList extends BaseCommand {
         ...BaseCommand.baseFlags,
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(CompileThreadList);
         const client = this.makeClient(flags);
         let data;
         try {
-            data = await client.get('/v1/compile/threads', { params: { model: args.face_id } });
+            data = await client.get('/v1/compile/threads', { params: { alias: args.face_id } });
         }
         catch (err) {
             if (err instanceof FacesAPIError)

package/dist/commands/face/create.d.ts

@@ -3,7 +3,7 @@ export default class FaceCreate extends BaseCommand {
     static description: string;
     static flags: {
         name: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        username: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        alias: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'default-model': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         formula: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/face/create.js

@@ -8,10 +8,10 @@ export default class FaceCreate extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         name: Flags.string({ description: 'Display name', required: true }),
-        username: Flags.string({ description: 'Unique username slug', required: true }),
+        alias: Flags.string({ description: 'Unique alias slug', required: true }),
         description: Flags.string({ description: 'Description for local catalog' }),
         'default-model': Flags.string({ description: 'Default LLM for chat (e.g. gpt-4o-mini, claude-sonnet-4-6)' }),
-        formula: Flags.string({ description: 'Boolean formula over owned concrete face usernames (e.g. "a | b", "(a | b) - c"). Creates a composite face.' }),
+        formula: Flags.string({ description: 'Boolean formula over owned concrete face aliases (e.g. "a | b", "(a | b) - c"). Creates a composite face.' }),
         attr: Flags.string({ description: 'Attribute KEY=VALUE (repeatable)', multiple: true }),
         tool: Flags.string({ description: 'Tool name to enable (repeatable)', multiple: true }),
     };
@@ -22,7 +22,7 @@ export default class FaceCreate extends BaseCommand {
         if (flags.formula && (flags.attr?.length || flags.tool?.length)) {
             this.error('--formula cannot be combined with --attr or --tool. Composite faces do not have compiled knowledge.');
         }
-        const payload = { name: flags.name, username: flags.username };
+        const payload = { name: flags.name, alias: flags.alias };
         if (flags.formula) {
             payload.formula = flags.formula;
         }

package/dist/commands/face/delete.js

@@ -10,7 +10,7 @@ export default class FaceDelete extends BaseCommand {
         yes: Flags.boolean({ description: 'Skip confirmation', default: false }),
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(FaceDelete);

package/dist/commands/face/diff.js

@@ -6,7 +6,7 @@ export default class FaceDiff extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         face: Flags.string({
-            description: 'Face username to include (repeatable, min 2)',
+            description: 'Face alias to include (repeatable, min 2)',
             multiple: true,
             required: true,
         }),

package/dist/commands/face/get.js

@@ -3,12 +3,12 @@ import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { flattenBasicFacts } from '../../utils.js';
 export default class FaceGet extends BaseCommand {
-    static description = 'Get details for a face by ID or username';
+    static description = 'Get details for a face by alias';
     static flags = {
         ...BaseCommand.baseFlags,
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(FaceGet);
@@ -26,7 +26,7 @@ export default class FaceGet extends BaseCommand {
         if (f.basic_facts)
             f.basic_facts = flattenBasicFacts(f.basic_facts);
         if (!this.jsonEnabled()) {
-            this.log(`id:        ${f.id}`);
+            this.log(`alias:     ${f.alias}`);
             this.log(`uid:       ${f.uid}`);
             this.log(`name:      ${f.name}`);
             this.log(`owned_by:  ${f.owned_by}`);

package/dist/commands/face/list.js

@@ -31,7 +31,7 @@ export default class FaceList extends BaseCommand {
                 this.log('(no faces)');
             }
             else {
-                const idWidth = Math.max(...faces.map(f => f.id.length));
+                const aliasWidth = Math.max(...faces.map(f => f.alias.length));
                 const nameWidth = Math.max(...faces.map(f => f.name.length));
                 for (const f of faces) {
                     let suffix = '';
@@ -44,7 +44,7 @@ export default class FaceList extends BaseCommand {
                         const profile = f.profile_token_count ?? 0;
                         suffix = `  [profile: ${profile} tok, components: ${total}]`;
                     }
-                    this.log(`${f.id.padEnd(idWidth)}  ${f.name.padEnd(nameWidth)}${suffix}`);
+                    this.log(`${f.alias.padEnd(aliasWidth)}  ${f.name.padEnd(nameWidth)}${suffix}`);
                 }
             }
         }

package/dist/commands/face/neighbors.js

@@ -23,7 +23,7 @@ export default class FaceNeighbors extends BaseCommand {
         }),
     };
     static args = {
-        face_id: Args.string({ description: 'Face username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(FaceNeighbors);

package/dist/commands/face/update.js

@@ -15,7 +15,7 @@ export default class FaceUpdate extends BaseCommand {
         tool: Flags.string({ description: 'Tool names to set (replaces list, repeatable)', multiple: true }),
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(FaceUpdate);

package/dist/commands/face/upload.js

@@ -23,7 +23,7 @@ export default class FaceUpload extends BaseCommand {
         }),
     };
     static args = {
-        face_id: Args.string({ description: 'Face ID or username', required: true }),
+        face_id: Args.string({ description: 'Face alias', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(FaceUpload);

package/dist/commands/keys/create.js

@@ -8,7 +8,7 @@ export default class KeysCreate extends BaseCommand {
         name: Flags.string({ description: 'Key name/label', required: true }),
         'expires-days': Flags.integer({ description: 'Expiry in days (omit for no expiry)' }),
         budget: Flags.string({ description: 'Spend budget in USD' }),
-        face: Flags.string({ description: 'Allowed face username (repeatable)', multiple: true }),
+        face: Flags.string({ description: 'Allowed face alias (repeatable)', multiple: true }),
         model: Flags.string({ description: 'Allowed model name (repeatable)', multiple: true }),
     };
     async run() {

package/oclif.manifest.json

@@ -1172,7 +1172,7 @@
       "aliases": [],
       "args": {
         "face_username": {
-          "description": "Face username (or face@model)",
+          "description": "Face alias (or alias@model)",
           "name": "face_username",
           "required": true
         }
@@ -1457,7 +1457,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -1771,9 +1771,9 @@
           "multiple": false,
           "type": "option"
         },
-        "username": {
-          "description": "Unique username slug",
-          "name": "username",
+        "alias": {
+          "description": "Unique alias slug",
+          "name": "alias",
           "required": true,
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1794,7 +1794,7 @@
           "type": "option"
         },
         "formula": {
-          "description": "Boolean formula over owned concrete face usernames (e.g. \"a | b\", \"(a | b) - c\"). Creates a composite face.",
+          "description": "Boolean formula over owned concrete face aliases (e.g. \"a | b\", \"(a | b) - c\"). Creates a composite face.",
           "name": "formula",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -1835,7 +1835,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -1933,7 +1933,7 @@
           "type": "option"
         },
         "face": {
-          "description": "Face username to include (repeatable, min 2)",
+          "description": "Face alias to include (repeatable, min 2)",
           "name": "face",
           "required": true,
           "hasDynamicHelp": false,
@@ -1961,12 +1961,12 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
       },
-      "description": "Get details for a face by ID or username",
+      "description": "Get details for a face by alias",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -2073,7 +2073,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -2219,7 +2219,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -2320,7 +2320,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -2473,7 +2473,7 @@
           "type": "option"
         },
         "face": {
-          "description": "Allowed face username (repeatable)",
+          "description": "Allowed face alias (repeatable)",
           "name": "face",
           "hasDynamicHelp": false,
           "multiple": true,
@@ -2704,7 +2704,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -3009,7 +3009,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -3110,7 +3110,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -3238,7 +3238,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -3499,7 +3499,7 @@
       "aliases": [],
       "args": {
         "face_id": {
-          "description": "Face ID or username",
+          "description": "Face alias",
           "name": "face_id",
           "required": true
         }
@@ -3753,5 +3753,5 @@
       ]
     }
   },
-  "version": "1.4.3"
+  "version": "1.4.4"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faces-cli",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "CLI for the Faces AI platform",
   "type": "module",
   "author": "sybileak <sybileak@proton.me>",