ffyi 0.2.0

CLI for friends.fyi

ffyi

CLI and Python client for friends.fyi.

Install

uv tool install ffyi

Installed commands: ffyi and fyi (alias).

CLI usage

fyi auth fyi_xxx
fyi whoami
fyi send alice "hello"
echo '{"status":"ok"}' | fyi send alice --sender "Deploy Bot"
fyi send alice '{"status":"ok"}' --type alert -H "X-Env: prod"
fyi send alice "anonymous ping" --no-auth
fyi inbox
fyi inbox --sender "Deploy Bot" --user-agent fyi-cli --type alert
fyi inbox 1d48f7c0-...
fyi inbox --json

Config is stored at:

• ~/.config/fyi/token
• ~/.config/fyi/server

Python usage

from fyi import FyiClient

client = FyiClient(api_key="fyi_xxx", base_url="https://friends.fyi")
client.send("alice", body='{"status":"ok"}', content_type="application/json", sender="Deploy Bot")
client.send("alice", body="hello", headers={"X-Type": "alert"}, authenticated=False)
messages = client.inbox(limit=20, sender="Deploy Bot")

API Surface (friends.fyi)

Public endpoints (no auth)

These are safe to call without session cookies or API keys. Bearer auth is optional on write endpoints and only affects sender identity/rate limits.

• GET /health
• GET /home
• GET /docs
• GET /api/docs
• POST /inbox/{username} (path-based inbox write)
• POST / (subdomain-based inbox write; host like alice.friends.fyi)

Private web/session endpoints (cookie-auth, browser)

These are browser endpoints. Use GitHub login + session cookie auth here, not API keys.

• GET /auth/login
• GET /auth/callback
• GET /auth/logout
• GET / (inbox page when logged in; landing page when logged out)
• GET /inbox/more (HTMX pagination partial)

Token-auth API endpoints (for CLI/agents)

These are private JSON endpoints for CLI/agents and should use Authorization: Bearer fyi_*.

• GET /api/me
• GET /api/token
• POST /api/token/rotate
• GET /inbox
• GET /inbox/{item_id}

Development

uv sync --extra dev
uv run pytest
uv build --clear

Publish

export UV_PUBLISH_TOKEN='pypi-...'
uv publish --check-url https://pypi.org/simple --publish-url https://upload.pypi.org/legacy/