Eve library

Lilith CLI Reference

Guide

Revision 1

On this page

Overview#

The Lilith CLI provides command-line tools for developers and operators to interact with Lilith services, manage deployments, and perform administrative tasks.

Installation#

bash
npm install -g @lilith/cli

From Source#

bash
git clone https://github.com/lilith/lilith
cd lilith
npm install
npm link

Configuration#

Environment Variables#

bash
export LILITH_API_KEY="your_api_key"
export LILITH_API_URL="https://api.lilith.app"  # Optional, defaults to production
export LILITH_ENV="production"                   # production, staging, local

Config File#

Create ~/.lilith/config.json:

json
{
  "api_key": "your_api_key",
  "api_url": "https://api.lilith.app",
  "default_persona": "zen_master",
  "output_format": "json"
}

Development Commands#

Service Management#

Start Services#

bash
# Start all services locally
npm run deploy

# Start specific services
npm run deploy -- --services auth,bff,ai

# Start with custom port
PORT=8081 npm run deploy

Stop Services#

bash
npm run deploy:stop

View Logs#

bash
# All services
npm run logs

# Specific service
npm run logs -- --service ai

# Error logs only
npm run logs:errors

Health Check#

bash
# Check all services
npm run health

# Wait for services (useful in CI)
npm run health:wait

Database Operations#

Seed Development Data#

bash
npm run seed:dev

Reset Databases#

bash
# Reset with backup
npm run reset:db

# Force reset (no backup)
npm run reset:force

Run Migrations#

bash
cd services/<service-name>
npm run db:migrate

Testing Commands#

Run Tests#

bash
# All tests
npm test

# Specific test file
npm test -- tests/chat.spec.ts

# With coverage
npm run coverage:run

E2E Tests#

bash
# Run E2E tests
npm run test:e2e

# Voice input tests
npm run test:e2e:voice

Performance Tests#

bash
# Chat load test
npm run perf:chat:burst

# TTS load test
npm run perf:tts:burst

# Soak test
npm run perf:soak

API Interaction Commands#

Authentication#

bash
# Login and save token
lilith auth login --email user@example.com

# Show current auth status
lilith auth status

# Logout
lilith auth logout

Chat#

bash
# Start interactive chat
lilith chat --persona zen_master

# Single message
lilith chat --persona zen_master --message "What is enlightenment?"

# With citations
lilith chat --persona zen_master --cite --message "Explain emptiness"

# Save conversation
lilith chat --persona zen_master --save conversation.json

Content#

bash
# List content
lilith content list --type meditation --tradition zen

# Get content detail
lilith content get <content_id>

# Download for offline
lilith content download <content_id> --output ./downloads/

Lectures#

bash
# Generate lecture
lilith lecture generate \
  --topic "Non-self in Buddhism" \
  --duration 10 \
  --tradition buddhism

# Check status
lilith lecture status <lecture_id>

# Download
lilith lecture download <lecture_id> --output ./lectures/

TTS#

bash
# Synthesize speech
lilith tts synthesize \
  --text "Hello, world" \
  --voice calm_female_1 \
  --output hello.opus

# From SSML file
lilith tts synthesize \
  --ssml-file script.ssml \
  --voice calm_female_1 \
  --output output.opus

# List voices
lilith tts voices

Administration Commands#

User Management#

bash
# List users (admin)
lilith admin users list --limit 50

# Get user details
lilith admin users get <user_id>

# Suspend user
lilith admin users suspend <user_id> --reason "policy violation"

Content Moderation#

bash
# View moderation queue
lilith admin moderation queue

# Review item
lilith admin moderation review <item_id> --action approve

# View safety metrics
lilith admin moderation metrics

Ingestion#

bash
# Submit document for ingestion
lilith admin ingest submit \
  --uri "s3://bucket/document.pdf" \
  --license "CC-BY-4.0" \
  --source-type scholarly

# Check ingestion status
lilith admin ingest status <job_id>

# List pending jobs
lilith admin ingest queue

Deployment Commands#

Docker#

bash
# Build all images
docker compose build

# Build specific service
docker compose build ai-service

# Push to registry
docker compose push

Kubernetes#

bash
# Deploy to cluster
kubectl apply -k deploy/kubernetes/overlays/staging

# Check deployment status
kubectl get pods -n lilith

# View logs
kubectl logs -n lilith -l app=ai-service -f

Helm#

bash
# Install/upgrade release
helm upgrade --install lilith deploy/helm/lilith-service \
  --namespace lilith \
  --values values-production.yaml

# Check release
helm status lilith -n lilith

# Rollback
helm rollback lilith 1 -n lilith

ArgoCD#

bash
# Sync application
argocd app sync lilith-app-of-apps

# Check sync status
argocd app get lilith-app-of-apps

# View diff
argocd app diff lilith-app-of-apps

Documentation Commands#

Generate Docs#

bash
# Generate all documentation
npm run docs:generate

# Validate documentation
npm run docs:validate

# Build and preview
npm run docs:build

API Documentation#

bash
# Validate OpenAPI spec
npm run docs:validate

# Generate code samples
npm run docs:generate-samples

# Publish to Stoplight
npm run docs:publish-stoplight

Utility Commands#

Format & Lint#

bash
# Lint all files
npm run lint

# Fix lint issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Type Checking#

bash
# Check types
npm run typecheck

# Watch mode
npm run typecheck:watch

Security#

bash
# Run security audit
npm run security:scan

# Static analysis
npm run security:sast

Output Formats#

Most commands support multiple output formats:

bash
# JSON output (default)
lilith content list --format json

# Table output
lilith content list --format table

# YAML output
lilith content list --format yaml

# Quiet (IDs only)
lilith content list --format quiet

Environment-Specific Commands#

Local Development#

bash
# Use local environment
LILITH_ENV=local lilith chat --persona zen_master

# Or set in config
lilith config set env local

Staging#

bash
LILITH_ENV=staging lilith chat --persona zen_master

Production#

bash
LILITH_ENV=production lilith chat --persona zen_master

Scripting Examples#

Bash Script#

bash
#!/bin/bash
# Generate multiple lectures

topics=("Zen meditation" "Stoic philosophy" "Sufi poetry")

for topic in "${topics[@]}"; do
  lilith lecture generate \
    --topic "$topic" \
    --duration 5 \
    --format json | jq -r '.lecture_id'
done

Node.js Script#

javascript
const { execSync } = require('child_process');

const result = execSync('lilith content list --format json');
const content = JSON.parse(result);

content.items.forEach((item) => {
  console.log(`${item.id}: ${item.title}`);
});

Troubleshooting#

Common Issues#

Authentication Failed

bash
# Clear cached credentials
lilith auth logout
rm -rf ~/.lilith/cache

# Re-authenticate
lilith auth login

Connection Refused

bash
# Check service health
npm run health

# Verify API URL
echo $LILITH_API_URL

Rate Limited

bash
# Wait and retry with backoff
lilith chat --message "..." --retry-with-backoff

Debug Mode#

bash
# Enable verbose logging
LILITH_DEBUG=1 lilith chat --persona zen_master

# Trace HTTP requests
LILITH_TRACE=1 lilith chat --persona zen_master

  • API Reference: http-api.md
  • Local Development: ../../docs/LOCAL_DEVELOPMENT_GUIDE.md
  • Deployment Guide: ../../docs/runbooks/procedures/deployment.md