Embeddr CLI

Your personal creative workspace — search, organize, and orchestrate artifacts, media, and AI workflows.

---

What is Embeddr?

Embeddr is a local-first, plugin-extensible workspace for managing your creative data. Think of it as a personal operating layer for artifacts — images, documents, code, workflows — with semantic search, a relation graph, AI tool integration, and a plugin system that lets you extend everything.

• Artifact-centric — everything is an artifact with typed metadata, relations, and lineage
• Plugin-extensible — add UI panels, backend routes, new capabilities, and AI tools
• AI-native — MCP server, LLM tool calling, Lotus agent integration
• Local-first — runs on your machine, your data stays yours

Installation

Using uv (recommended)

mkdir embeddr && cd embeddr
uv venv && source .venv/bin/activate

# Install Torch — https://pytorch.org/get-started/locally/
# CPU only:
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
# Or CUDA 13.0:
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130

# Install Embeddr
uv pip install embeddr-cli

Using pip

pip install embeddr-cli

Quick Start

# Initialize a workspace
embeddr init

# Start the server
embeddr serve

✨ Embeddr Local API has started!
   ---------------------------------------------
   👉 Web UI:    http://127.0.0.1:8003
   ---------------------------------------------
   Press Ctrl+C to stop server

CLI Reference

embeddr serve

Start the Embeddr API server with the web UI.

embeddr serve [OPTIONS]

Options:
  --host TEXT         Host to bind to [default: 127.0.0.1]
  --port INTEGER      Port to bind to [default: 8003]
  --plugins-dir TEXT   Directory to load plugins from
  --mcp               Enable Model Context Protocol endpoint
  --docs              Enable API documentation at /docs
  --reload            Enable live reload for development
  --no-plugins        Start without loading plugins
  --verbose           Verbose logging

Worker mode (distributed processing):
  --worker            Run as a headless worker node
  --main-url TEXT     URL of the main Embeddr instance
  --worker-key TEXT   Authentication key for worker registration
  --worker-name TEXT  Worker display name
  --worker-tags TEXT  Comma-separated worker tags

embeddr init

Interactive setup wizard for a new workspace. Creates embeddr.toml project config, initializes the database, and walks you through auth and plugin configuration.

embeddr config

embeddr config init    # Create embeddr.toml in current directory
embeddr config show    # Display current configuration and paths

embeddr lotus

Interact with the Lotus capability system from the command line.

embeddr lotus list [--kind action] [--plugin embeddr-llm] [--query "search"]
embeddr lotus query "image generation"
embeddr lotus inspect <capability_id>
embeddr lotus invoke <capability_id> [--input key=value]

Other Commands

Command	Description
embeddr db	Database management (migrations, schema)
embeddr plugins	Plugin lifecycle management
embeddr process	Artifact processing (scan, embed, analyze)
embeddr inspect	Query artifacts, metadata, and relations
embeddr tui	Interactive terminal UI explorer
embeddr system	System resources and ML model management
embeddr manage	Account and API key operations
embeddr debug	Inspect executions, sessions, auth state

Global Options

--data-dir, -d TEXT   Override data directory (also: EMBEDDR_DATA_DIR env var)

Integrations

Model Context Protocol (MCP)

Embeddr exposes an MCP endpoint so any MCP-compatible client can use your workspace as a tool server.

embeddr serve --mcp

mcp.json

{
  "mcpServers": {
    "embeddr": {
      "url": "http://localhost:8003/mcp/messages",
      "timeout": 120000
    }
  }
}

Works with Claude Desktop, Mistral Vibe, Cursor, and anything that supports the Model Context Protocol.

ComfyUI Extension

Send ComfyUI workflow outputs directly to Embeddr with full lineage tracking.

comfy node install embeddr-extension

View on ComfyUI Registry

Lotus CLI

AI agent REPL that connects to your Embeddr workspace. Bring your own LLM provider.

pip install lotus-cli
lotus connect
lotus

Plugins

Extend Embeddr with custom functionality. Plugins can add UI panels, backend routes, database models, and Lotus capabilities.

1. Download or create a plugin
2. Place it in your plugins directory (default: ~/.local/share/embeddr/plugins)
3. Restart Embeddr

Check out the Plugin Development Guide and Plugin Examples.

Auth

Four authentication modes to match your deployment:

Mode	Description
open	No auth required (default for local dev)
single	Single API key for all access
multi	Multiple users with scoped API keys
db	Full database-backed user accounts

Configure via embeddr.toml or EMBEDDR_AUTH_MODE env var.

Screenshots

Zen Shell — Full Workspace

Panel-based workspace with image browser, media frame, ComfyUI runner, and generation settings.

Zen Mode — Floating Panels

Minimal floating panel layout with cosmic theme.

Editor — Generation Workflow

Ink/manga style generation with layer editor plugin and lineage tracking.

Theming

Fully themeable — dark, light, and custom color schemes.

Lineage

Artifact relation graph showing generation provenance.

Development

git clone https://github.com/embeddr-net/embeddr-cli
cd embeddr-cli
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Install Torch for your platform

# Start with live reload
embeddr serve --reload --docs

Releases include the bundled frontend. For development, run the frontend dev server or download the latest release and extract it into embeddr-cli/src/web/.

Packages

License

Copyright 2026 Embeddr Labs and Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0