CLI Reference
Complete reference for the reflexio command-line tool — global options, shortcuts, and command groups.
CLI Reference
The reflexio CLI is the primary entry point for managing interactions, profiles, and playbooks from the terminal. It is installed alongside the Python client and shares the same authentication (REFLEXIO_API_KEY / REFLEXIO_URL).
Installation
The reflexio CLI ships in the reflexio-ai package, which bundles the client, the FastAPI server, and the CLI together. Install it whenever you need to run a local server, manage data from the terminal, or use the integration wizards.
pip install reflexio-aiOr with uv:
uv add reflexio-aiAfter installation the reflexio command is available on your PATH.
Managed-only Python users don't need this package. If you only call the Python SDK against managed Reflexio Enterprise from your application code, install the lightweight reflexio-client instead — it has no server, no CLI, and a much smaller dependency footprint. See the API Reference Initialization page.
Setup
The CLI talks to a Reflexio server. There are two modes — pick the one that matches your deployment.
Enterprise
Managed Reflexio is a hosted service at https://www.reflexio.ai. It runs the backend, storage, and extraction pipeline for you — there is nothing to install or start on your machine.
Export your API key and you are done. The CLI already defaults to the managed endpoint, so REFLEXIO_URL does not need to be set.
export REFLEXIO_API_KEY="your-api-key"
# Ready to go
reflexio status whoami
reflexio publish --user-id user_123 \
--user-message "Find me a flight to Tokyo" \
--agent-response "Searching flights..."You can also save the key persistently:
reflexio auth login --api-key your-api-keyThe services, doctor, and self-hosted config storage / config pull commands do not apply to managed Reflexio — the cloud handles server lifecycle, health, and credentials for you.
Run the open-source Reflexio server locally. The default setup is a single-process FastAPI backend on http://localhost:8081 backed by SQLite — no authentication, no external database.
export REFLEXIO_URL="http://localhost:8081"
# Start the backend
reflexio services start
# In another terminal, use the CLI against it
reflexio publish --user-id user_123 \
--user-message "Find me a flight to Tokyo" \
--agent-response "Searching flights..."No API key is required for the default open-source build. See services for the full start/stop reference and setup init for an interactive wizard that configures LLM providers for you.
Invocation
reflexio --help
reflexio <group> <command> [OPTIONS]Every command group and subcommand supports --help. If you forget a flag, run reflexio <group> <command> --help to see the exact signature.
Global options
These flags are accepted before any subcommand and apply to every command group.
Prop
Type
Example:
reflexio --json user-profiles list --limit 5Command groups
Commands marked Both work against either managed or self-hosted deployments. Commands marked Self-hosted only operate on a local server and are not used with managed Reflexio.
interactions — Both
Publish, list, search, and delete user-agent conversations.
user-profiles — Both
Manage user profiles extracted from interactions.
agent-playbooks / user-playbooks — Both
Manage playbook rules, aggregation, and approval workflow.
auth / status — Both
Authenticate to a Reflexio server and inspect org/storage identity.
api — Both
Make raw HTTP calls to any Reflexio endpoint.
setup — Both
Interactive wizards — includes a Managed Reflexio path alongside local and self-hosted options.
config — Mostly self-hosted
config show / config set target the server you are connected to. config storage / config pull are for copying managed credentials down to a local machine.
services — Self-hosted open-source only
Start and stop a local open-source backend (SQLite, no auth) and docs site. Not used with managed Reflexio.
doctor — Self-hosted only
Diagnose a local Reflexio setup. Managed users can use status check / status whoami instead.
Top-level shortcuts
Three commands are registered directly on the root app because they are the most common operations. They are thin wrappers that dispatch to the relevant sub-group.
reflexio publish
Alias for reflexio interactions publish. See interactions for the full option list.
# Single-turn capture
reflexio publish \
--user-id user_123 \
--user-message "Find me a flight to Tokyo" \
--agent-response "Searching flights..."reflexio search
Unified semantic search across profiles and user playbooks in a single call.
reflexio search "morning commute" --top-k 5 --user-id user_123Prop
Type
reflexio context
Fetch formatted bootstrap context for agent injection: the top-scoring profiles and user playbooks concatenated into a single string you can drop into a system prompt.
reflexio context --user-id user_123 --agent-version v1Prop
Type
Environment variables
Every variable the CLI reads. Command-line flags always take precedence.
| Variable | Scope | Purpose |
|---|---|---|
REFLEXIO_URL | CLI | Backend server URL. Defaults to https://www.reflexio.ai (managed). Set to http://localhost:8081 for a local self-hosted server. Override with --server-url. |
REFLEXIO_API_KEY | CLI + Python SDK | Bearer token for authentication. Required for managed Reflexio; optional for an open-source self-hosted server. Override with --api-key. |
REFLEXIO_USER_ID | CLI | Default user ID used by commands that need one. Override with --user-id. |
REFLEXIO_AGENT_VERSION | CLI | Default agent version tag. Override with --agent-version. |
REFLEXIO_STORAGE | Self-hosted only | Storage backend for services start. Defaults to sqlite — the open-source default requires no extra setup. Override with --storage. |
BACKEND_PORT | Self-hosted only | Backend port for services start/stop. Default 8081. |
DOCS_PORT | Self-hosted only | Docs site port for services start/stop. Default 8082. |
Heads-up: the Python SDK uses a different env var for the URL. The reflexio-client and reflexio-ai Python SDKs read REFLEXIO_API_URL, not REFLEXIO_URL. Both default to https://www.reflexio.ai/. If you use both the CLI and the Python SDK, set both env vars (or pass --server-url / url_endpoint explicitly). See the API Reference Initialization page for the SDK's env-var contract.
The CLI auto-loads a .env file from the current directory, then from ~/.reflexio/.env. Use reflexio auth login to write REFLEXIO_URL and REFLEXIO_API_KEY to the user-level file.