faces-cli 0.1.0

CLI for the Faces AI platform

faces-cli

Command-line interface for the Faces AI platform.

Install

pip install faces-cli

Requires Python ≥ 3.11.

Quick Start

# Login
faces auth login

# Create a face
faces face create --name "My Bot" --username my-bot

# Chat with it
faces chat chat my-bot --message "Hello!"

# Check your balance
faces billing balance

Authentication

The CLI stores credentials at ~/.faces/config.json.

faces auth login            # interactive email + password
faces auth whoami           # verify current session
faces auth logout           # clear credentials

API key (no login required):

export FACES_API_KEY=sk-proj-...
faces face list

Global Options

faces [--base-url URL] [--token TOKEN] [--api-key KEY] [--json/--no-json] COMMAND

• --json (default): JSON output, ideal for piping to jq
• --no-json: human-readable output
• FACES_BASE_URL, FACES_TOKEN, FACES_API_KEY env vars are respected

Command Groups

Group	Commands
auth	login, logout, register, whoami, refresh
face	create, list, get, update, delete, stats, upload
chat	chat, messages, responses
compile	doc (create/list/get/prepare/sync/delete), thread (create/list/message/sync)
keys	create, list, revoke, update (JWT required)
billing	balance, subscription, quota, usage, topup, checkout, card-setup
account	state
config	set, show, clear

Run faces COMMAND --help for detailed options on any command.

Examples

Face management

faces face create --name "Research Bot" --username research-bot \
  --attr "domain=AI research" --attr "language=English"

faces face list | jq '.[].username'

faces face update research-bot --attr "domain=machine learning"
faces face delete research-bot --yes

Inference

# Simple chat
faces chat chat research-bot -m "What are the latest trends in AI?"

# Specify LLM
faces chat chat research-bot --llm gpt-4o -m "Summarize my notes"

# Stream response
faces chat chat research-bot --stream -m "Write a long essay about..."

# Anthropic Messages API
faces chat messages research-bot@claude-sonnet-4-6 -m "Hello"

# OpenAI Responses API
faces chat responses research-bot@gpt-4o -m "Hello"

Compiling to face memory

# Upload a file
faces face upload <face_id> --file report.pdf --kind document

# Or create inline
DOC=$(faces compile doc create <face_id> --label "Notes" --content "Important info...")
DOC_ID=$(echo $DOC | jq -r '.id')

faces compile doc prepare $DOC_ID
faces compile doc sync $DOC_ID --yes

API keys

# JWT login required
faces auth login

faces keys create --name "Partner key" --face my-bot --budget 10 --expires-days 90
faces keys list
faces keys revoke <key_id> --yes

Billing

faces billing balance
faces billing subscription
faces billing quota
faces billing topup --amount 20
faces billing checkout --plan standard

Agent / Claude Code Usage

See SKILL.md for the Claude Code agent skill definition.

License

The faces-cli tool is released under the MIT License.

Note: The MIT license applies solely to this CLI tool. It does not apply to the Faces platform, its API, or any underlying codebase or services operated by Headwaters.