Metadata-Version: 2.1
Name: conserver-cli
Version: 0.1.0
Summary: CLI tool to manage vcon-server Docker containers
Home-page: https://github.com/vcon-dev/vcon-server-cli
License: MIT
Keywords: vcon,docker,cli,conserver,voice-conversation
Author: Thomas Howe
Author-email: thomas@strolid.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Dist: click (>=8.1.7,<8.2.0)
Requires-Dist: docker (>=7.1.0,<8.0.0)
Requires-Dist: httpx (>=0.27.0,<0.28.0)
Requires-Dist: pydantic (>=2.6.0,<3.0.0)
Requires-Dist: pydantic-settings (>=2.2.0,<3.0.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: rich (>=13.7.0,<14.0.0)
Requires-Dist: typer[all] (>=0.12.0,<0.13.0)
Project-URL: Repository, https://github.com/vcon-dev/vcon-server-cli
Description-Content-Type: text/markdown

# 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
- **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
```

### 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 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

