Metadata-Version: 2.2
Name: faces-cli
Version: 0.1.0
Summary: CLI for the Faces AI platform
Author-email: Headwaters <sretawdaeh@proton.me>
Keywords: faces,ai,cli,llm,agent
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13

# faces-cli

Command-line interface for the [Faces AI platform](https://faces.sh).

## Install

```bash
pip install faces-cli
```

Requires Python ≥ 3.11.

## Quick Start

```bash
# 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`.

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

API key (no login required):

```bash
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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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](./SKILL.md) for the Claude Code agent skill definition.

## License

The `faces-cli` tool is released under the [MIT License](./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.
