conserver-cli 0.2.0
CLI tool to manage vcon-server Docker containers
License: MIT
Requires Python: <4.0,>=3.10
Keywords: vcon, docker, cli, conserver, voice-conversation

# Conserver CLI

[![PyPI version](https://badge.fury.io/py/conserver-cli.svg)](https://badge.fury.io/py/conserver-cli)
[![Tests](https://github.com/vcon-dev/vcon-server-cli/actions/workflows/test.yml/badge.svg)](https://github.com/vcon-dev/vcon-server-cli/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

A command-line tool to manage [vcon-server](https://github.com/vcon-dev/vcon-server) Docker containers.

## Quick Start

```bash
# Install
pipx install conserver-cli

# Start the server
conserver start

# Check status
conserver status

# View logs
conserver logs -f
```

## Features

- **Container Management**: Start, stop, restart, and upgrade vcon-server containers
- **Image Management**: List, pull, upgrade, and downgrade vcon-server images from ECR
- **Configuration Management**: View, edit, and validate configuration files
- **Health Monitoring**: Check service health with detailed diagnostics
- **Log Viewing**: Stream and filter container logs
- **Rich Terminal UI**: Beautiful tables, colors, and progress indicators

## Installation

### Using pipx (Recommended)

```bash
pipx install conserver-cli
```

### Using pip

```bash
pip install conserver-cli
```

### Using Homebrew (macOS/Linux)

```bash
brew tap vcon-dev/tap
brew install conserver
```

### From Source

```bash
git clone https://github.com/vcon-dev/vcon-server-cli.git
cd vcon-server-cli
poetry install
poetry shell
conserver --help
```

## Requirements

- Python 3.10+
- Docker and Docker Compose
- vcon-server installation

## Usage

### Container Commands

```bash
# Start all containers
conserver start

# Start with build
conserver start --build

# Start specific services
conserver start --services api,redis

# Stop containers
conserver stop

# Stop and remove containers
conserver stop --remove

# Restart containers
conserver restart

# Upgrade to latest version
conserver upgrade

# Upgrade with dry-run
conserver upgrade --dry-run
```

### Status and Monitoring

```bash
# Show container status
conserver status

# Show status with health details
conserver status --health

# Watch status continuously
conserver status --watch

# Output as JSON
conserver status --format json

# Check service health
conserver health

# View logs
conserver logs

# Follow logs
conserver logs -f

# Show last 50 lines
conserver logs --tail 50

# Filter logs
conserver logs --grep "error"

# Logs for specific service
conserver logs api
```

### Configuration

```bash
# Initialize configuration from examples
conserver config init

# Show current configuration
conserver config show

# Show .env file
conserver config show --file env

# Show with secrets unmasked
conserver config show --secrets

# Edit configuration
conserver config edit

# Edit specific file
conserver config edit --file env

# Set a value
conserver config set REDIS_URL redis://localhost:6379 --file env
conserver config set links.transcribe.options.model_size large --file config

# Validate configuration
conserver config validate
```

### Image Management

```bash
# List available remote tags
conserver images list --remote

# List local images
conserver images list

# Pull specific version
conserver images pull v1.2.0

# Pull latest main branch
conserver images pull main

# Switch to a version (and restart)
conserver images use v1.2.0 --restart

# Upgrade to latest version
conserver images upgrade

# Downgrade to older version
conserver images downgrade v1.1.0

# Show image info
conserver images info v1.2.0

# Remove old images (keep 3 most recent)
conserver images prune
```

### Server Path

By default, conserver looks for the vcon-server installation in:
1. `--server-path` CLI option
2. `VCON_SERVER_PATH` environment variable
3. Common relative locations (`./vcon-server`, `../vcon-server`)

```bash
# Specify server path
conserver start --server-path /path/to/vcon-server

# Or set environment variable
export VCON_SERVER_PATH=/path/to/vcon-server
conserver start
```

## Command Reference

| Command | Description |
|---------|-------------|
| `conserver start` | Start containers |
| `conserver stop` | Stop containers |
| `conserver restart` | Restart containers |
| `conserver status` | Show container status |
| `conserver health` | Check service health |
| `conserver logs` | View container logs |
| `conserver upgrade` | Upgrade to latest version |
| `conserver images list` | List available images |
| `conserver images pull` | Pull an image |
| `conserver images use` | Switch to a version |
| `conserver images upgrade` | Upgrade image version |
| `conserver images downgrade` | Downgrade image version |
| `conserver config show` | Show configuration |
| `conserver config edit` | Edit configuration |
| `conserver config set` | Set a config value |
| `conserver config validate` | Validate configuration |
| `conserver config init` | Initialize from examples |

## Configuration Files

Conserver manages these configuration files in your vcon-server installation:

| File | Description |
|------|-------------|
| `.env` | Environment variables (REDIS_URL, API tokens, etc.) |
| `config.yml` | Application configuration (links, chains, storages) |
| `docker-compose.yml` | Docker container definitions |

## Development

### Setup

```bash
git clone https://github.com/vcon-dev/vcon-server-cli.git
cd vcon-server-cli
poetry install
poetry shell
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=conserver --cov-report=html

# Run specific test file
pytest tests/test_cli.py -v
```

### Code Quality

```bash
# Lint
ruff check .

# Format
ruff format .

# Type check
mypy conserver
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Related Projects

- [vcon-server](https://github.com/vcon-dev/vcon-server) - The vCon processing server
- [vcon](https://github.com/vcon-dev/vcon) - vCon specification and libraries