CLI

CLI Reference

Local OSS CLI reference for services, configuration, diagnostics, and data operations.

The reflexio CLI is the command-line interface for Local OSS. Use it to start a local backend, configure settings, publish interactions, inspect profiles and playbooks, and diagnose the local service.

For a guided first run, start with Local OSS Get Started.

The open-source default is a local FastAPI backend on http://localhost:8081, SQLite storage, and no authentication.

Installation

The CLI ships in the reflexio-ai package, which also includes the Python SDK and local FastAPI server.

Terminal

pip install reflexio-ai

Or with uv:

Terminal

uv add reflexio-ai

After installation, confirm the command is on your PATH:

Terminal

reflexio --version
reflexio --help

Local Setup

The shortest open-source path is:

Terminal

export OPENAI_API_KEY="your-openai-key"
reflexio services start

Then, in another terminal:

Terminal

export REFLEXIO_URL="http://localhost:8081"
reflexio status check

You can also use the interactive wizard:

Terminal

reflexio setup init

Choose Local SQLite for the default open-source server. The wizard writes persistent settings to ~/.reflexio/.env.

Invocation

Terminal

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	Default	Description
`--json?`	`flag`	`false`	Emit structured JSON envelopes on stdout instead of human-formatted output. Use this when piping into jq or another tool.
`--server-url?`	`str`	`"https://www.reflexio.ai"`	Backend API server URL. Overrides REFLEXIO_URL for this invocation.
`--api-key?`	`str`	`env: REFLEXIO_API_KEY`	API key for authentication, sent as a Bearer token. Not required for the default open-source local server.
`--version?`	`flag`	`false`	Print the installed reflexio version and exit.

Example:

Terminal

reflexio --json user-profiles list --limit 5

Command Groups

services

Start and stop the local open-source backend, docs site, and optional embedding daemon.

setup

Run interactive setup for local storage, provider keys, and supported integrations.

config

Inspect and update server configuration for extractors, LLMs, storage, playbooks, and evaluation.

interactions

Publish, list, search, and delete user-agent conversations.

user-profiles

Manage user profiles extracted from local interactions.

agent-playbooks / user-playbooks

Manage playbook rules, aggregation, and approval workflow.

embeddings

Run the local OpenAI-compatible embedding daemon directly.

auth / status

Persist connection settings and inspect the server identity.

diagnostics

Run local health checks and make raw API calls while debugging.

Top-Level Shortcuts

Three commands are registered directly on the root app because they are common during local development. They are thin wrappers around the command groups.

`reflexio publish`

Alias for reflexio interactions publish. See interactions for the full option list.

Terminal

reflexio publish \
  --user-id user_123 \
  --user-message "Find me a flight to Tokyo" \
  --agent-response "Searching flights..." \
  --source local-demo \
  --session-id session_001

`reflexio search`

Unified semantic search across profiles and user playbooks in a single call.

Terminal

reflexio search "morning commute" --top-k 5 --user-id user_123

Prop	Type	Default	Description
`QUERY?`	`str (positional)`	`—`	Natural-language query text.
`--top-k?`	`int`	`5`	Maximum number of results per entity type.
`--threshold?`	`float`	`model-specific`	Similarity threshold (0.0 - 1.0). Omit it to use the embedding model's default.
`--user-id?`	`str`	`none`	Filter profiles by user ID.
`--agent-version?`	`str`	`none`	Filter playbooks by agent version.
`--tag?`	`str (repeatable)`	`none`	Match entities having any of these tags (OR semantics). Repeat the flag for multiple tags. Omit to disable tag filtering.

`reflexio context`

Fetch formatted bootstrap context for agent injection: top-scoring profiles and playbooks concatenated into a string you can add to a system prompt.

Terminal

reflexio context --user-id user_123 --agent-version local-demo

Prop	Type	Default	Description
`--user-id?`	`str`	`—`	User ID for profile lookup. Required.
`--agent-version?`	`str`	`—`	Agent version for playbook filtering. Required.
`--query?`	`str`	`"general preferences"`	Search query used to rank results.

Environment Variables

Every variable below can be used with the open-source CLI. Command-line flags take precedence.

Variable	Purpose
`REFLEXIO_URL`	Backend server URL. Set to `http://localhost:8081` for the default local server. Override with `--server-url`.
`REFLEXIO_API_KEY`	Optional API key for servers that require authentication, sent as a Bearer token. Not needed for the default open-source local server. Override with `--api-key`.
`REFLEXIO_USER_ID`	Default user ID used by commands that need one. Override with `--user-id`.
`REFLEXIO_AGENT_VERSION`	Default agent version tag. Override with `--agent-version`.
`REFLEXIO_STORAGE`	Storage backend for `services start`. Open-source local starts default to `sqlite`. Override with `--storage`.
`BACKEND_PORT`	Backend port for `services start/stop`. Default `8081`.
`DOCS_PORT`	Docs site port for `services start/stop`. Default `8082`.
`EMBEDDING_PORT`	Local embedding daemon port for `services start/stop` and `embeddings serve`. Default `8072`.
`REFLEXIO_EMBEDDING_PROVIDER`	Embedding provider mode: `cloud`, `local_service`, `internal_service`, or `off`. Reflexio-hosted models always run in the embedding-service process.
`REFLEXIO_EMBEDDING_SERVICE_URL`	OpenAI-compatible embedding endpoint used by `local_service` and `internal_service`.

The Python SDK and CLI share the same URL env var. Set REFLEXIO_URL once and both tools point at the same local server. See Initialization & Authentication for the SDK contract.

The CLI auto-loads a .env file from the current directory, then from ~/.reflexio/.env. Use reflexio setup init for the guided open-source setup.