# Lilith CLI Reference

## 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](./http-api.md)
- **Local Development**: `../../docs/LOCAL_DEVELOPMENT_GUIDE.md`
- **Deployment Guide**: `../../docs/runbooks/procedures/deployment.md`
