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

!faces config:show 2>/dev/null || echo "(no config saved)"

Setup

Before running any command, verify credentials are available:

faces config:show          # see what's saved
faces auth:whoami          # confirm login works

If no credentials exist and the user hasn't provided a key:

• For interactive sessions: run faces auth:login and prompt for email + password
• For API-key-only context: tell the user to set FACES_API_KEY=<key> or run faces config:set api_key <key>

Install (if faces command not found):

npm install -g faces-cli

Auth rules

Core workflow

1. Create a Face: faces face:create --name "Name" --username slug
2. Compile source material into it — local files or YouTube URLs
3. Sync to extract and embed cognitive primitives
4. Chat through the Face: faces chat:chat slug -m "message"
5. Compare Faces: faces face:diff or faces face:neighbors
6. Compose new Faces from boolean formulas: faces face:create --formula "a | b"

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

Common tasks

Compile a document into a face

DOC_ID=$(faces compile:doc:create <face_id> --label "Notes" --file notes.txt --json | jq -r '.id')
faces compile:doc:prepare "$DOC_ID"
faces compile:doc:sync "$DOC_ID" --yes

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

faces face:upload <face_id> --file report.pdf --kind document
faces face:upload <face_id> --file interview.mp4 --kind thread

Import a YouTube video

# Solo talk / monologue → document
faces compile:import <face_id> \
  --url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --type document --perspective first-person

# Then prepare and sync:
faces compile:doc:prepare <doc_id>
faces compile:doc:sync <doc_id> --yes

# Multi-speaker → thread (no prepare step needed)
faces compile:import <face_id> \
  --url "https://youtu.be/VIDEO_ID" \
  --type thread --perspective first-person --face-speaker A
faces compile:thread:sync <thread_id>

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

Create a composite face

faces face:create --name "The Realist" --username the-realist \
  --formula "the-optimist | the-pessimist"

# Chat through it like any other face
faces chat:chat the-realist -m "How do you approach risk?"

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

faces face:diff --face aria --face marco --face jin
faces face:neighbors aria --k 3
faces face:neighbors aria --component beta --direction furthest --k 5

Chat with a specific LLM

faces chat:chat slug --llm claude-sonnet-4-6 -m "message"
faces chat:messages slug@claude-sonnet-4-6 -m "message" --max-tokens 512
faces chat:responses slug@gpt-4o -m "message"

Billing and API keys

faces billing:balance --json
faces billing:subscription --json
faces keys:create --name "Partner key" --face slug --budget 10.00 --expires-days 30

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:prepare returns "processing" — Extraction is async. Poll with faces compile:doc:get <doc_id> --json | jq '.status' until status is ready, then sync.
• 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 synced yet. Run the compile+sync workflow first.

References

• See references/REFERENCE.md for the full command reference, global flags, and environment variables.
• 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/SCOPE.md for instruction scope and security boundaries.