LiteMind CLI

  _     _ _       __  __ _           _    ____ _     ___ 
 | |   (_) |_ ___|  \/  (_)_ __   __| |  / ___| |   |_ _|
 | |   | | __/ _ \ |\/| | | '_ \ / _` | | |   | |    | | 
 | |___| | ||  __/ |  | | | | | | (_| | | |___| |___ | | 
 |_____|_|\__\___|_|  |_|_|_| |_|\__,_|  \____|_____|___|

         Terminal interface for LiteMindUI  ·  Chat · RAG

A fully-featured terminal user interface (TUI) for the LiteMindUI backend, built with Textual.

Chat with local and cloud AI models, and query your own documents — all from your terminal, with no browser required.

Features

Requirements

• Python ≥ 3.11
• A running LiteMindUI backend at http://localhost:8000 (quick-start here)
• uv (recommended) or pip

Quick start

1. Start the LiteMindUI backend

The CLI is a frontend — it needs the backend running first.

# Option A — Docker (easiest)
curl -fsSL https://raw.githubusercontent.com/debabratamishra/litemind-ui/main/install.sh | bash

# Option B — from source
git clone https://github.com/debabratamishra/litemind-ui.git
cd litemind-ui
make up

Backend will be available at http://localhost:8000.

2. Install and run litemind-cli

git clone https://github.com/debabratamishra/litemind-cli.git
cd litemind-cli

# Install dependencies
uv sync

# (Optional) configure environment
cp .env.example .env
# edit .env if your backend runs somewhere other than localhost:8000

# Launch the TUI
uv run litemind-cli

Or install globally as a tool:

uv tool install .
litemind-cli

Usage

Usage: litemind-cli [OPTIONS] COMMAND [ARGS]...

  LiteMind CLI — terminal interface for the LiteMindUI backend.

Options:
  -b, --backend TEXT   Backend URL  [env: FASTAPI_URL]
  -m, --model TEXT     Default model name  [env: DEFAULT_MODEL]
  --version            Show version and exit
  --help               Show this message and exit

Commands:
  chat    Open the TUI on the Chat tab
  rag     Open the TUI on the RAG tab
  login   Authenticate with the backend and save your JWT token
  status  Check backend connectivity and print available models

Examples

# Open on the Chat tab (default)
litemind-cli

# Open directly on the RAG tab
litemind-cli rag

# Use a remote backend
litemind-cli --backend http://192.168.1.10:8000

# Override model at launch
litemind-cli --model mistral:7b

# Check if the backend is reachable
litemind-cli status

# Authenticate with the backend (required for chat/rag when auth is enabled)
litemind-cli login

# Login against a specific backend
litemind-cli login --backend http://192.168.1.10:8000

Authentication

The LiteMindUI backend uses GoTrue (Supabase) for authentication. When the backend has auth enabled, the CLI needs a JWT token to access chat and RAG endpoints.

To get a token:

1. Run litemind-cli login — you'll be prompted for your email and password. The CLI calls the backend's /api/auth/login endpoint and stores the token in memory for the session.
2. Or set BACKEND_TOKEN in your .env file with a pre-generated JWT.

To generate a token manually (e.g., for CI or scripting):

# Using Python with PyJWT (install: pip install PyJWT)
python3 -c "
import jwt, time
secret = '<GOTRUE_JWT_SECRET from the backend .env>'
now = int(time.time())
payload = {
    'sub': 'cli-user',
    'email': 'you@example.com',
    'user_metadata': {'name': 'CLI User'},
    'iat': now,
    'exp': now + 86400 * 30,   # 30 days
}
print(jwt.encode(payload, secret, algorithm='HS256'))
"

The GOTRUE_JWT_SECRET is found in the backend's .env file. The token must be a valid HS256 JWT with a sub claim.

Inside the TUI

Switching providers

The toolbar at the top of both Chat and RAG tabs has an inline provider selector:

API base URLs are pre-filled automatically when you switch provider. You only need to enter your API key.

OpenRouter model format: provider/model-name
e.g. openai/gpt-4o, anthropic/claude-3.5-sonnet, meta-llama/llama-3.3-70b-instruct

NIM model format: org/model-name
e.g. meta/llama-3.3-70b-instruct, nvidia/llama-3.1-nemotron-70b-instruct

RAG — uploading documents

In the RAG tab, enter one or more file paths (space-separated) in the upload field and click Upload:

/Users/me/docs/report.pdf /Users/me/notes/meeting.md

Supported formats: PDF, DOCX, TXT, MD, CSV, XLSX, PPTX, HTML, ODT, RTF, YAML, JSON

Keyboard shortcuts

Configuration

All options can be set in a .env file (copy from .env.example) or as environment variables. CLI flags always take precedence.

Example .env for OpenRouter with backend auth:

FASTAPI_URL=http://localhost:8000
DEFAULT_BACKEND=openrouter
DEFAULT_MODEL=openai/gpt-4o-mini
API_KEY=sk-or-your-key-here
BACKEND_TOKEN=eyJhbGciOiJIUzI1NiIs...

Project layout

litemind_cli/
  config.py              env / config loading (singleton)
  app.py                 Textual App — MainScreen + SplashScreen
  main.py                Typer CLI entrypoint
  services/
    backend_service.py   health check, model listing
    chat_service.py      streaming chat (SSE parser included)
    rag_service.py       file upload, RAG query streaming
  screens/
    splash_screen.py     ASCII art intro (auto-dismisses after 3 s)
    chat_screen.py       Chat panel (Widget)
    rag_screen.py        RAG panel (Widget)
    settings_screen.py   Settings panel (Widget)
  widgets/
    message_list.py      scrollable chat bubble widget

Dependencies

Related

• litemind-ui — FastAPI backend + Streamlit web frontend
• API contract — HTTP API reference for frontend developers