Local OSS

CLI Reference

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

CLI Reference

The emend 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.

Info

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

Installation

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

pip install emend-ai

Or with uv:

uv add emend-ai

After installation, confirm the command is on your PATH:

emend --versionemend --help

Local Setup

The shortest open-source path is:

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

Then, in another terminal:

export EMEND_URL="http://localhost:8081"emend status check

You can also use the interactive wizard:

emend setup init

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

Invocation

emend --helpemend <group> <command> [OPTIONS]

Every command group and subcommand supports --help. If you forget a flag, run emend <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
`--json`	flag
`--server-url`	str
`--api-key`	str
`--version`	flag

Example:

emend --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.

emend publish

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

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

emend search

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

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

Prop	Type
`QUERY`	str (positional)
`--top-k`	int
`--threshold`	float
`--user-id`	str
`--agent-version`	str
`--tag`	str (repeatable)

emend context

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

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

Prop	Type
`--user-id`	str
`--agent-version`	str
`--query`	str

Environment Variables

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

Variable	Purpose
EMEND_URL	Backend server URL. Set to `http://localhost:8081` for the default local server. Override with `--server-url`.
EMEND_API_KEY	Optional bearer token for servers that require authentication. Not needed for the default open-source local server. Override with `--api-key`.
EMEND_USER_ID	Default user ID used by commands that need one. Override with `--user-id`.
EMEND_AGENT_VERSION	Default agent version tag. Override with `--agent-version`.
EMEND_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.
EMEND_EMBEDDING_PROVIDER	Embedding provider mode: `cloud`, `local_service`, `internal_service`, or `off`. Emend-hosted models always run in the embedding-service process.
EMEND_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 EMEND_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 ~/.emend/.env. Use emend setup init for the guided open-source setup.

PreviousAdvanced Portal Use Next interactions