modbender Faces Skill
You have access to the faces CLI. Use it to fulfill any Faces platform request.
Current config
!faces config:show 2>/dev/null || echo "(no config saved)"
Setup check
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:loginand prompt for email + password - For API-key-only context: tell the user to set
FACES_API_KEY=<key>or runfaces config:set api_key <key>
Install (if faces command not found):
npm install -g faces-cli
Auth rules
| Command group | Requires |
|---|---|
faces auth:*, faces keys:* |
JWT only — run faces auth:login first |
| Everything else | JWT or API key |
Output format
Add --json to any command for machine-readable JSON output (required for jq pipelines):
faces face:list --json | jq '.[].username'
faces billing:balance --json | jq '.balance_usd'
faces compile:doc:list <face_id> --json | jq '.[] | {id, label, status}'
Without --json, commands print human-readable text.
Common tasks
Login
faces auth:login --email user@example.com --password secret
faces auth:whoami --json
Create a face and chat with it
faces face:create --name "Jony Five" --username jony-five
faces chat:chat jony-five --message "Hello!"
# With a specific LLM
faces chat:chat jony-five --llm claude-sonnet-4-6 --message "Hello!"
# Stream response
faces chat:chat jony-five --stream --message "Write a long response"
Compile a document into a face
# Step 1 — create the document
DOC_ID=$(faces compile:doc:create <face_id> --label "Notes" --file notes.txt --json | jq -r '.id')
# Step 2 — run LLM extraction
faces compile:doc:prepare "$DOC_ID"
# Step 3 — sync to face (charges compile quota; --yes skips confirm)
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
Check billing state
faces billing:balance --json # credits + payment method status
faces billing:subscription --json # plan, face count, renewal date
faces billing:quota --json # compile token usage per face
Create a scoped API key
# JWT required — keys cannot manage themselves
faces keys:create \
--name "Partner key" \
--face jony-five \
--budget 10.00 \
--expires-days 30
Anthropic Messages proxy
faces chat:messages jony-five@claude-sonnet-4-6 \
--message "What do you know about me?" \
--max-tokens 512
OpenAI Responses proxy
faces chat:responses jony-five@gpt-4o \
--message "Summarize my recent work"
Full command reference
faces auth:login --email --password
faces auth:logout
faces auth:register --email --password --name --username [--invite-key]
faces auth:whoami
faces auth:refresh
faces face:create --name --username [--attr KEY=VALUE]... [--tool NAME]...
faces face:list
faces face:get <face_id>
faces face:update <face_id> [--name] [--attr KEY=VALUE]...
faces face:delete <face_id> [--yes]
faces face:stats
faces face:upload <face_id> --file PATH --kind document|thread
faces chat:chat <face_username> -m MSG [--llm MODEL] [--system] [--stream]
[--max-tokens N] [--temperature F] [--file PATH]
faces chat:messages <face@model> -m MSG [--system] [--stream] [--max-tokens N]
faces chat:responses <face@model> -m MSG [--instructions] [--stream]
faces compile:doc:create <face_id> [--label] (--content TEXT | --file PATH)
faces compile:doc:list <face_id>
faces compile:doc:get <doc_id>
faces compile:doc:prepare <doc_id>
faces compile:doc:sync <doc_id> [--yes]
faces compile:doc:delete <doc_id>
faces compile:thread:create <face_id> [--label]
faces compile:thread:list <face_id>
faces compile:thread:message <thread_id> -m MSG
faces compile:thread:sync <thread_id>
faces keys:create --name [--expires-days N] [--budget F] [--face USERNAME]... [--model NAME]...
faces keys:list
faces keys:revoke <key_id> [--yes]
faces keys:update <key_id> [--name] [--budget F] [--reset-spent]
faces billing:balance
faces billing:subscription
faces billing:quota
faces billing:usage [--group-by api_key|model|llm|date] [--from DATE] [--to DATE]
faces billing:topup --amount F [--payment-ref REF]
faces billing:checkout --plan standard|pro
faces billing:card-setup
faces billing:llm-costs [--provider openai|anthropic|...]
faces account:state
faces config:set <key> <value>
faces config:show
faces config:clear [--yes]
Global flags (any command):
faces [--base-url URL] [--token JWT] [--api-key KEY] [--json] COMMAND
Env vars: FACES_BASE_URL, FACES_TOKEN, FACES_API_KEY
Instruction Scope
Runtime instructions operate exclusively on the faces CLI, which sends HTTPS requests to the Faces platform API (api.faces.sh by default, or FACES_BASE_URL if set). No local files are read or written except ~/.faces/config.json, which stores credentials the user explicitly provides.
Install: the CLI is installed via npm install -g faces-cli from the public npm registry (npmjs.com/package/faces-cli), published by sybileak. The source is the faces-cli-js repository under the Headwaters AI organization.
Credentials: the skill uses a JWT (FACES_TOKEN) or API key (FACES_API_KEY) to authenticate requests — proportionate to a REST API client. Credentials are only read from environment variables or ~/.faces/config.json; they are never written anywhere other than that config file when the user explicitly runs faces auth:login or faces config:set. The skill may prompt for email and password during auth:login; these are sent directly to the Faces API and not stored in plaintext (only the resulting JWT is saved). Scoped API keys with budget limits and expiry are recommended over long-lived account credentials.
Scope boundaries: instructions stay within the Faces platform domain (auth, face management, inference, compile, billing, API keys). No system commands, file operations, or network requests outside of faces * CLI calls are issued. The jq utility is used solely for extracting fields from JSON output in example pipelines.