ftl-expert

CLI client for expert-service — ask questions, search beliefs, and query domain knowledge bases from the terminal or Claude Code.

The CLI command is expert (not ftl-expert).

Install from PyPI

pip install ftl-expert

Or with uv:

uv tool install ftl-expert

Run Without Installing

uvx --from ftl-expert expert ask "What is EEM?"

Install from Source

pip install git+https://github.com/benthomasson/expert.git

Quick Start

No setup required — the CLI defaults to querying the public eem-expert knowledge base:

expert ask "What is EEM?"
expert search "epistemic memory"
expert explain eem-definition

To connect to your own expert-service instance, create a config:

expert init
# Edit ~/.config/expert/config.toml with your settings

Configuration

Config file: ~/.config/expert/config.toml

Default (works out of the box):

url = "https://expert.ftl2.com"
project = "eem-expert"
anonymous = true

For authenticated access to your own instance:

url = "http://localhost:8000"
project = "your-project"
anonymous = false
api_key = "your-api-key"
# Or use Google OAuth:
# google_client_id = "your-id.apps.googleusercontent.com"
# google_client_secret = "your-secret"

Environment variables override config file values, CLI flags override both:

Config Key	Environment Variable	Description
url	EXPERT_URL	expert-service base URL
api_key	EXPERT_API_KEY	Static API key (alternative to OAuth)
project	EXPERT_PROJECT	Default project name
anonymous	EXPERT_ANONYMOUS	Skip auth for public projects
google_client_id	GOOGLE_CLIENT_ID	Google OAuth client ID
google_client_secret	GOOGLE_CLIENT_SECRET	Google OAuth client secret

Commands

expert ask <question>

Ask a question and get a complete answer. Uses dual-path retrieval (TMS beliefs + full-text search). When the server is in data-only mode, automatically falls back to local LLM synthesis.

expert ask "What is EEM?"
expert ask "How does the TMS work?" --project eem-expert

expert search <query>

Keyword search over beliefs and entries. No LLM involved — fast full-text search.

expert search "epistemic memory"
expert search "truth maintenance"

expert chat <message>

Streaming chat response. Same as ask but streams tokens as they arrive. Falls back to local LLM when the server is in data-only mode.

expert chat "Explain the difference between EEM and RAG"

expert projects

List all available projects with belief, entry, and source counts.

expert login

Authenticate via Google OAuth. Opens a browser, exchanges an auth code via localhost callback, and caches the token at ~/.config/expert/token.json. Tokens auto-refresh on subsequent calls.

expert login
expert login --port 9090

expert logout

Clear cached OAuth credentials.

expert status

Show current authentication state, service URL, and default project.

expert init

Create a default config file at ~/.config/expert/config.toml.

Authentication

Three modes:

1. Anonymous (default) — no setup needed. Access public projects like eem-expert. Set anonymous = true in config or leave auth unconfigured.

2. Google OAuth — run expert login, tokens are cached and auto-refreshed. Provides per-user identity and RBAC via expert-service's user table.

3. Static API key — set api_key in config or EXPERT_API_KEY env var. Grants admin access. Useful for scripts and CI.

Claude Code Skill

Install the /expert skill for use in Claude Code sessions:

expert install-skill

Then in Claude Code:

/expert ask what is EEM?
/expert search epistemic memory
/expert explain eem-definition

Architecture

Claude Code / Terminal
       |
   expert CLI (httpx)
       |
expert-service (FastAPI)
  +-- TMS beliefs (PostgreSQL)
  +-- FTS sources (tsvector)
  +-- Connectors
       +-- Snowflake (live business data)
       +-- Dataverse (live business data)
       +-- PageIndex (document retrieval)

License

MIT