faces-cli 1.6.1 → 1.6.3

package/README.md

@@ -1,6 +1,6 @@
 # faces-cli
 
-Command-line interface for the [Faces](https://faces.sh) platform.
+Command-line interface for the [Faces](https://faces.sh) platform. Compile source material into AI personas with cognitive primitives, then chat with them, compare them, and compose them.
 
 ## Installation
 
@@ -8,43 +8,76 @@ Command-line interface for the [Faces](https://faces.sh) platform.
 npm install -g faces-cli
 ```
 
-Requires Node.js ≥ 18.
+Requires Node.js >= 18.
 
 ## Quick start
 
 ```bash
-faces auth login
-faces face list
-faces chat chat myface -m "Hello"
+# Register or login
+faces auth:register --email you@example.com --password 'YourPass123!' --username you
+faces auth:login --email you@example.com --password 'YourPass123!'
+
+# Create a face
+faces face:create --name "Alice" --alias alice --default-model gpt-5.4-mini \
+  --attr gender=female --attr age=29 --attr occupation="product designer"
+
+# Add source material and compile
+faces compile:doc alice --file essay.txt --no-wait
+faces compile:upload alice --file interview.mp3 --kind thread --no-wait
+
+# Chat
+faces chat:chat alice -m "What matters most to you?"
+faces chat:chat alice -m "Tell me more" --llm claude-sonnet-4-6
+
+# Compare and compose
+faces face:diff --face alice --face bob
+faces face:create --name "Alice-Bob" --alias alice-bob --formula "alice | bob"
 ```
 
 ## Commands
 
 ```
-faces auth login / logout / register / whoami / refresh
-faces face create / list / get / update / delete / stats / upload
-faces chat chat / messages / responses
-faces compile doc create / list / get / prepare / sync / delete
-faces compile thread create / list / message / sync
-faces keys create / list / revoke / update
-faces billing balance / subscription / quota / usage / topup / checkout / card-setup / llm-costs
-faces account state
-faces config set / show / clear
+faces auth:login / logout / register / whoami / refresh
+faces auth:connect / disconnect / connections
+
+faces face:create / list / get / update / delete / stats / attributes
+faces face:upload / diff / neighbors
+
+faces chat:chat / messages / responses
+
+faces compile:doc / compile:doc:create / list / get / edit / make / pause / reset / delete
+faces compile:thread:create / list / get / edit / message / make / pause / reset / sync / delete
+faces compile:upload / compile:import
+faces compile:all
+
+faces catalog:list / doctor / backup / restore / manyfaced
+
+faces keys:create / list / revoke / update
+
+faces billing:balance / subscription / quota / usage / topup / checkout / card-setup / llm-costs
+
+faces account:state / preferences
+
+faces config:set / show / clear
 ```
 
 Run `faces <command> --help` for details on any command.
 
 ## Authentication
 
-Login stores a JWT at `~/.faces/config.json` (shared with the Python `faces-cli`).
-You can also authenticate via environment variables:
+Login stores a JWT at `~/.faces/config.json`. You can also authenticate via environment variables:
 
 ```bash
-export FACES_API_KEY=your_api_key
+export FACES_API_KEY=sk-faces-...
 export FACES_TOKEN=your_jwt
 export FACES_BASE_URL=https://api.faces.sh   # optional override
 ```
 
+## Plans
+
+- **Pay-per-token** — $5 activation (added as credits), 5% markup on all API calls. No monthly fee.
+- **Subscription Connect** ($17/month) — same 5% markup, plus link your ChatGPT Plus/Pro account to use select OpenAI models at no extra cost for compilation and inference.
+
 ## License
 
 MIT — Copyright (c) 2026 Headwaters Lab Inc.

package/dist/catalog.d.ts

@@ -5,21 +5,30 @@ export interface FaceFrontmatter {
     description?: string;
     alias: string;
     attributes?: Record<string, string>;
+    tags?: string[];
+    default_model?: string;
+    formula?: string | null;
     component_counts?: {
         alpha: number;
         beta: number;
         delta: number;
         epsilon: number;
     };
+    compiled_tokens?: number;
     profile_token_count?: number;
+    [key: string]: unknown;
 }
 export interface FaceDataInput {
     name: string;
     alias: string;
     uid?: string;
+    description?: string | null;
     basic_facts?: Record<string, string | {
         value: string;
     }> | null;
+    tags?: string[] | null;
+    default_model?: string | null;
+    formula?: string | null;
     component_counts?: {
         alpha: number;
         beta: number;
@@ -27,10 +36,13 @@ export interface FaceDataInput {
         epsilon: number;
     } | null;
     profile_token_count?: number | null;
+    total_tokens_saved?: number | null;
 }
 export declare class CatalogService {
     isEnabled(): boolean;
     writeFace(faceData: FaceDataInput, description?: string): void;
-    deleteFace(username: string): void;
+    deleteFace(alias: string): void;
+    /** Update just tags on an existing FACE.md without touching other fields */
+    updateTags(alias: string, tags: string[]): void;
     rebuildIndex(): void;
 }

package/dist/catalog.js

@@ -5,7 +5,7 @@ import { loadConfig } from './config.js';
 export const CATALOG_DIR = path.join(os.homedir(), '.faces', 'catalog');
 export const CATALOG_INDEX = path.join(os.homedir(), '.faces', 'catalog.json');
 function quoteYaml(value) {
-    if (/[:#\[\]{}&*!|>'"%@`]/.test(value) || value !== value.trim() || value === '') {
+    if (/[:#\[\]{}&*!|>'"%@`\n]/.test(value) || value !== value.trim() || value === '') {
         return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
     }
     return value;
@@ -16,16 +16,26 @@ function serializeFrontmatter(fm) {
     if (fm.description)
         lines.push(`description: ${quoteYaml(fm.description)}`);
     lines.push(`alias: ${quoteYaml(fm.alias)}`);
+    if (fm.default_model)
+        lines.push(`default_model: ${quoteYaml(fm.default_model)}`);
+    if (fm.formula)
+        lines.push(`formula: ${quoteYaml(fm.formula)}`);
     if (fm.attributes && Object.keys(fm.attributes).length > 0) {
         lines.push('attributes:');
         for (const [k, v] of Object.entries(fm.attributes)) {
             lines.push(`  ${k}: ${quoteYaml(String(v))}`);
         }
     }
+    if (fm.tags && fm.tags.length > 0) {
+        lines.push(`tags: [${fm.tags.join(', ')}]`);
+    }
     if (fm.component_counts) {
         const cc = fm.component_counts;
         lines.push(`component_counts: ${cc.alpha + cc.beta + cc.delta + cc.epsilon}`);
     }
+    if (fm.compiled_tokens) {
+        lines.push(`compiled_tokens: ${fm.compiled_tokens}`);
+    }
     if (fm.profile_token_count) {
         lines.push(`profile_token_count: ${fm.profile_token_count}`);
     }
@@ -35,12 +45,14 @@ function serializeFrontmatter(fm) {
 function parseFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
     if (!match)
-        return { frontmatter: null, body: content };
+        return { frontmatter: null, body: content, extraKeys: {} };
     const yamlBlock = match[1];
     const body = match[2];
     const fm = {};
+    const extraKeys = {};
     let inAttributes = false;
     const attributes = {};
+    const knownKeys = new Set(['name', 'description', 'alias', 'attributes', 'tags', 'default_model', 'formula', 'component_counts', 'compiled_tokens', 'profile_token_count']);
     for (const line of yamlBlock.split('\n')) {
         if (line.startsWith('  ') && inAttributes) {
             const colonIdx = line.indexOf(':');
@@ -63,14 +75,30 @@ function parseFrontmatter(content) {
             fm.description = val;
         else if (key === 'alias')
             fm.alias = val;
+        else if (key === 'default_model')
+            fm.default_model = val;
+        else if (key === 'formula')
+            fm.formula = val;
         else if (key === 'attributes')
             inAttributes = true;
+        else if (key === 'tags') {
+            const inner = val.replace(/^\[/, '').replace(/\]$/, '');
+            fm.tags = inner ? inner.split(',').map(s => s.trim()).filter(Boolean) : [];
+        }
+        else if (key === 'compiled_tokens')
+            fm.compiled_tokens = Number(val) || undefined;
+        else if (key === 'profile_token_count')
+            fm.profile_token_count = Number(val) || undefined;
+        else if (!knownKeys.has(key)) {
+            // Preserve agent/user-managed keys
+            extraKeys[key] = val;
+        }
     }
     if (Object.keys(attributes).length > 0)
         fm.attributes = attributes;
     if (!fm.name || !fm.alias)
-        return { frontmatter: null, body: content };
-    return { frontmatter: fm, body };
+        return { frontmatter: null, body: content, extraKeys: {} };
+    return { frontmatter: fm, body, extraKeys };
 }
 const DEFAULT_BODY = '\n## Notes\n\n';
 export class CatalogService {
@@ -82,12 +110,13 @@ export class CatalogService {
         if (!this.isEnabled())
             return;
         try {
-            const username = faceData.alias;
-            const dir = path.join(CATALOG_DIR, username);
+            const alias = faceData.alias;
+            const dir = path.join(CATALOG_DIR, alias);
             fs.mkdirSync(dir, { recursive: true });
             const filePath = path.join(dir, 'FACE.md');
             let existingBody = DEFAULT_BODY;
             let existingDescription;
+            let existingExtraKeys = {};
             if (fs.existsSync(filePath)) {
                 const existing = fs.readFileSync(filePath, 'utf8');
                 const parsed = parseFrontmatter(existing);
@@ -95,17 +124,26 @@ export class CatalogService {
                     existingBody = parsed.body;
                 if (parsed.frontmatter?.description)
                     existingDescription = parsed.frontmatter.description;
+                existingExtraKeys = parsed.extraKeys;
             }
             const fm = {
                 name: faceData.name,
-                alias: username,
+                alias,
             };
+            // Description: explicit arg > existing > API response
             if (description) {
                 fm.description = description;
             }
+            else if (faceData.description) {
+                fm.description = faceData.description;
+            }
             else if (existingDescription) {
                 fm.description = existingDescription;
             }
+            if (faceData.default_model)
+                fm.default_model = faceData.default_model;
+            if (faceData.formula)
+                fm.formula = faceData.formula;
             if (faceData.basic_facts && Object.keys(faceData.basic_facts).length > 0) {
                 const attrs = {};
                 for (const [k, v] of Object.entries(faceData.basic_facts)) {
@@ -113,10 +151,19 @@ export class CatalogService {
                 }
                 fm.attributes = attrs;
             }
+            if (faceData.tags && faceData.tags.length > 0)
+                fm.tags = faceData.tags;
             if (faceData.component_counts)
                 fm.component_counts = faceData.component_counts;
             if (faceData.profile_token_count)
                 fm.profile_token_count = faceData.profile_token_count;
+            if (faceData.total_tokens_saved)
+                fm.compiled_tokens = faceData.total_tokens_saved;
+            // Preserve agent/user-managed extra keys
+            for (const [k, v] of Object.entries(existingExtraKeys)) {
+                if (!(k in fm))
+                    fm[k] = v;
+            }
             const content = serializeFrontmatter(fm) + '\n' + existingBody;
             fs.writeFileSync(filePath, content);
             this.rebuildIndex();
@@ -126,11 +173,11 @@ export class CatalogService {
             process.stderr.write(`warn: catalog write failed: ${msg}\n`);
         }
     }
-    deleteFace(username) {
+    deleteFace(alias) {
         if (!this.isEnabled())
             return;
         try {
-            const dir = path.join(CATALOG_DIR, username);
+            const dir = path.join(CATALOG_DIR, alias);
             fs.rmSync(dir, { recursive: true, force: true });
             this.rebuildIndex();
         }
@@ -139,6 +186,28 @@ export class CatalogService {
             process.stderr.write(`warn: catalog delete failed: ${msg}\n`);
         }
     }
+    /** Update just tags on an existing FACE.md without touching other fields */
+    updateTags(alias, tags) {
+        if (!this.isEnabled())
+            return;
+        try {
+            const filePath = path.join(CATALOG_DIR, alias, 'FACE.md');
+            if (!fs.existsSync(filePath))
+                return;
+            const content = fs.readFileSync(filePath, 'utf8');
+            const parsed = parseFrontmatter(content);
+            if (!parsed.frontmatter)
+                return;
+            parsed.frontmatter.tags = tags;
+            const newContent = serializeFrontmatter(parsed.frontmatter) + '\n' + parsed.body;
+            fs.writeFileSync(filePath, newContent);
+            this.rebuildIndex();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`warn: catalog tag update failed: ${msg}\n`);
+        }
+    }
     rebuildIndex() {
         if (!this.isEnabled())
             return;

package/dist/client.d.ts

@@ -33,6 +33,10 @@ export declare class FacesClient {
         body?: unknown;
     }): Promise<ResponseWithHeaders>;
     postNoAuth(path: string, body: unknown): Promise<unknown>;
+    put(path: string, opts?: {
+        requireJwt?: boolean;
+        body?: unknown;
+    }): Promise<unknown>;
     patch(path: string, opts?: {
         requireJwt?: boolean;
         body?: unknown;

package/dist/client.js

@@ -141,6 +141,22 @@ export class FacesClient {
             throw await this.parseError(resp);
         return resp.json();
     }
+    async put(path, opts = {}) {
+        let resp;
+        try {
+            resp = await fetch(this.url(path), {
+                method: 'PUT',
+                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);
+        return resp.json();
+    }
     async patch(path, opts = {}) {
         let resp;
         try {

package/dist/commands/catalog/backup.js

@@ -3,9 +3,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
-import { flattenBasicFacts } from '../../utils.js';
+import { flattenAttributes } from '../../utils.js';
 export default class CatalogBackup extends BaseCommand {
-    static description = 'Snapshot all faces and source material for migration';
+    static description = 'Snapshot all faces, teams, and source material for migration';
     static flags = {
         ...BaseCommand.baseFlags,
     };
@@ -13,10 +13,10 @@ export default class CatalogBackup extends BaseCommand {
         const { flags } = await this.parse(CatalogBackup);
         const client = this.makeClient(flags);
         const json = this.jsonEnabled();
-        // Fetch all faces
+        // Fetch all faces with tags included
         let faces;
         try {
-            const resp = await client.get('/v1/faces');
+            const resp = await client.get('/v1/faces?include=tags');
             faces = (resp.data ?? resp);
         }
         catch (err) {
@@ -31,13 +31,17 @@ export default class CatalogBackup extends BaseCommand {
             const alias = face.alias;
             if (!json)
                 process.stderr.write(`  ${alias}: `);
+            // Tags and description come from the enriched list response
+            const tags = face.tags ?? [];
             const entry = {
                 alias,
                 name: face.name,
-                basic_facts: face.basic_facts ? flattenBasicFacts(face.basic_facts) : null,
+                description: face.description ?? null,
+                basic_facts: face.basic_facts ? flattenAttributes(face.basic_facts) : null,
                 default_model: face.default_model ?? null,
                 default_tools: face.default_tools ?? [],
                 formula: face.formula ?? null,
+                tags,
                 documents: [],
                 threads: [],
             };
@@ -52,9 +56,7 @@ export default class CatalogBackup extends BaseCommand {
                     });
                 }
             }
-            catch {
-                // face may have no documents
-            }
+            catch { /* face may have no documents */ }
             // Fetch threads
             try {
                 const threads = await client.get('/v1/compile/threads', { params: { alias } });
@@ -68,22 +70,66 @@ export default class CatalogBackup extends BaseCommand {
                             messages,
                         });
                     }
-                    catch {
-                        // skip threads we can't fetch
-                    }
+                    catch { /* skip threads we can't fetch */ }
                 }
             }
-            catch {
-                // face may have no threads
-            }
+            catch { /* face may have no threads */ }
             if (!json)
-                process.stderr.write(`${entry.documents.length} doc(s), ${entry.threads.length} thread(s)\n`);
+                process.stderr.write(`${entry.documents.length} doc(s), ${entry.threads.length} thread(s), ${tags.length} tag(s)\n`);
             backupFaces.push(entry);
         }
+        // Fetch teams
+        const backupTeams = [];
+        try {
+            const resp = await client.get('/v1/me/teams');
+            let teams = resp.data ?? resp;
+            teams = teams.filter(t => t.kind !== 'personal');
+            for (const team of teams) {
+                const teamId = team.id;
+                if (!json)
+                    process.stderr.write(`  team ${team.name}: `);
+                // Fetch members
+                let memberAliases = [];
+                try {
+                    const membersResp = await client.get(`/v1/teams/${teamId}/members`);
+                    const members = membersResp.data ?? [];
+                    // Build uid→alias map from original face list
+                    const uidToAlias = new Map();
+                    for (const f of faces) {
+                        if (f.uid)
+                            uidToAlias.set(f.uid, f.alias);
+                    }
+                    for (const m of members) {
+                        const iamId = m.iam_id;
+                        const alias = uidToAlias.get(iamId) ?? iamId;
+                        memberAliases.push(alias);
+                    }
+                }
+                catch { /* no members */ }
+                // Fetch tags
+                let teamTags = [];
+                try {
+                    const tagResp = await client.get(`/v1/teams/${teamId}/tags`);
+                    teamTags = tagResp.tags ?? [];
+                }
+                catch { /* no tags */ }
+                backupTeams.push({
+                    name: team.name,
+                    description: team.description ?? null,
+                    protocol: team.protocol ?? null,
+                    tags: teamTags,
+                    members: memberAliases,
+                });
+                if (!json)
+                    process.stderr.write(`${memberAliases.length} member(s), ${teamTags.length} tag(s)\n`);
+            }
+        }
+        catch { /* no teams */ }
         const backup = {
-            version: 1,
+            version: 2,
             created_at: new Date().toISOString(),
             faces: backupFaces,
+            teams: backupTeams,
         };
         const backupDir = path.join(os.homedir(), '.faces', 'backups');
         fs.mkdirSync(backupDir, { recursive: true });
@@ -94,8 +140,8 @@ export default class CatalogBackup extends BaseCommand {
         const totalThreads = backupFaces.reduce((n, f) => n + f.threads.length, 0);
         if (!json) {
             this.log(`\nBackup saved: ${filePath}`);
-            this.log(`  ${backupFaces.length} face(s), ${totalDocs} document(s), ${totalThreads} thread(s)`);
+            this.log(`  ${backupFaces.length} face(s), ${totalDocs} document(s), ${totalThreads} thread(s), ${backupTeams.length} team(s)`);
         }
-        return { path: filePath, faces: backupFaces.length, documents: totalDocs, threads: totalThreads };
+        return { path: filePath, faces: backupFaces.length, documents: totalDocs, threads: totalThreads, teams: backupTeams.length };
     }
 }