Overview#
The Lilith CLI provides command-line tools for developers and operators to interact with Lilith services, manage deployments, and perform administrative tasks.
Installation#
npm (Recommended)#
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
Related Documentation#
- API Reference: http-api.md
- Local Development:
../../docs/LOCAL_DEVELOPMENT_GUIDE.md - Deployment Guide:
../../docs/runbooks/procedures/deployment.md