Faces Skill

You have access to the faces CLI. Use it to fulfill any Faces Platform request.

Always use --json when you need to extract values from command output.

Current config

Setup

Verify credentials: faces auth:whoami. If no credentials exist, see references/AUTH.md for registration (requires human payment step) and login.

Install (if faces command not found): INLINECODE5

INLINECODE6 and faces keys:* require JWT. Everything else accepts JWT or API key.

Plans

Two plans: Free ($5 minimum initial spend, pay-per-token with 5% markup on all usage including compilation) and Connect ($17/month, 100k compile tokens/month, free passthrough to OpenAI Codex for users with a ChatGPT subscription). See references/AUTH.md for details.

Core workflow

1. 1. Create a Face with basic facts and a default model: INLINECODE8
2. Compile source material in one step: INLINECODE9

1. 3. Chat through the Face: faces chat:chat slug -m "message" (auto-routes to the correct API based on model provider)
2. Compare Faces: faces face:diff or INLINECODE12
3. Compose new Faces from boolean formulas: INLINECODE13

Note: compile:doc handles the full create → compile pipeline. For an already-created document, use compile:doc:make <doc_id>. Threads use a separate workflow: compile:thread:make (same fire-and-forget pattern as documents).

Boolean operators: | (union), & (intersection), - (difference), ^ (symmetric difference). Parentheses supported: (a | b) - c.

Common tasks

Create a face with attributes

When creating a Face, set basic demographic facts with --attr KEY=VALUE (repeatable). Common keys: gender, age, location, occupation, education_level, religion, ethnicity, nationality, marital_status. Unrecognized keys are silently ignored — see references/ATTRIBUTES.md for the complete list of accepted keys.

CODEBLOCK0

You can also add or update attributes and set the default model on an existing Face:
CODEBLOCK1

Compile a document into a face

Upload a file (PDF, audio, video, text)

Thread transcript format

Text files uploaded as threads must use Speaker Name: message format, one turn per line:

CODEBLOCK4

Use --face-speaker to specify which speaker IS the face (maps to role=user). All other speakers become role=assistant. If omitted, the first speaker is assumed to be the face.

Audio/video files with --kind thread are transcribed with speaker diarization — speaker labels are assigned automatically (Speaker A, Speaker B, etc.). Use --face-speaker A to map the correct speaker to the face.

Import a YouTube video

If --type thread fails with a 422, retry with --type document.

Create a composite face

Composite faces are live: sync new knowledge into any component and the composite updates automatically. Components must be concrete (compiled) faces you own.

Compare faces

Chat

INLINECODE40 auto-routes to the correct API endpoint based on model provider (Anthropic → /v1/messages, OpenAI/others → /v1/chat/completions). If the face has a default_model set, no --llm flag is needed.

CODEBLOCK8

Face templates

Use ${face-username} in any message to reference another face's profile inline. The token is replaced with the face's display name and the profile is injected as context. A bare model name (no face prefix) skips the persona and lets you reference all faces via templates.

CODEBLOCK9

See references/TEMPLATES.md for full details and rules.

Billing and API keys

Common errors

• - faces: command not found — Run npm install -g faces-cli.
• 401 Unauthorized — Credentials missing or expired. Run faces auth:login or check FACES_API_KEY.
• compile:doc:make returns "preparing" — Compilation is async. Poll with faces compile:doc:get <doc_id> --json | jq -r '.prepare_status' until status is synced.
• 422 on thread import — No speaker segments detected. Retry with --type document.
• face:diff or face:neighbors returns null components — The face hasn't been compiled yet. Run faces compile:doc <face_id> --file ... first.

References

• - See references/QUICKSTART.md for the end-to-end guide: install → register → create → compile → chat.
• See references/REFERENCE.md for the full command reference, global flags, and environment variables.
• See references/AUTH.md for registration, login, API keys, and credential management.
• See references/CONCEPTS.md for a detailed explanation of what Faces is, how it works, and example use cases.
• See references/OAUTH.md for connecting a ChatGPT account (connect plan only).
• See references/TEMPLATES.md for face template syntax (${face-username}) and bare model usage.
• See references/ATTRIBUTES.md for the complete list of accepted --attr keys (unrecognized keys are silently ignored).
• See references/SCOPE.md for instruction scope and security boundaries.