faces-cli

Command-line interface for the Faces platform. Compile source material into AI personas with cognitive primitives, then chat with them, compare them, and compose them.

Installation

npm install -g faces-cli

Requires Node.js >= 18.

Quick start

# Register or login
faces auth:register --email [email protected] --password 'YourPass123!' --username you
faces auth:login --email [email protected] --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 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. You can also authenticate via environment variables:

export FACES_API_KEY=sk-faces-...
export FACES_TOKEN=your_jwt
export FACES_BASE_URL=https://api-alpha.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.