cheshire-cat-cli 0.1.0
A CLI tool to start your local AI cat server
Requires Python: >=3.10

<div align="center">

# 🐱 Cheshire Cat CLI

**Your friendly command-line companion for managing Cheshire Cat AI**

A simple, powerful CLI tool to start, manage, and sync your local AI cat server with ease.

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Usage](#-usage) • [Cloud Sync](#-cloud-synchronization)

</div>

---

## 🎯 What is Cheshire Cat CLI?

The **Cheshire Cat CLI** is a command-line interface tool that simplifies the management of your [Cheshire Cat AI](https://github.com/cheshire-cat-ai/core) server. No need to mess with Docker commands or compose files manually—just simple commands to get your AI cat up and running!

Whether you're a developer experimenting with AI, or someone looking to run a personal AI assistant, this CLI makes it effortless to:
- 🚀 Start and stop your AI server with a single command
- 🔄 Keep your server updated to the latest version
- ☁️ Sync your cat's memory, plugins, and data across multiple machines

## ✨ Features

- **🎮 Simple Commands**: Intuitive commands that just work
- **🐳 Docker Powered**: Uses Docker Compose under the hood—no manual configuration needed
- **☁️ Cloud Synchronization**: Keep your AI cat's brain synced across devices
  - Supports WebDAV and Nextcloud
  - Automatic sync on start/stop
  - Manual sync on demand
- **⚡ Detached Mode**: Run your server in the background
- **🔧 Easy Updates**: Update to the latest version with one command
- **📦 Lightweight**: Minimal dependencies, maximum functionality

## 📋 Requirements

Before installing, make sure you have:
- **Python 3.10 or higher**
- **Docker** and **Docker Compose** installed and running
- A cup of tea ☕ (optional, but recommended)

## 🚀 Installation

Install the Cheshire Cat CLI with pip:

```bash
pip install cheshire-cat-cli
```

That's it! You're ready to go. 🎉

## 🏃 Quick Start

Start your Cheshire Cat AI server in just three steps:

```bash
# 1. Start the server
ccat start

# 2. Open your browser and visit http://localhost:1865
# 3. Start chatting with your AI cat! 🐱
```

Stop the server when you're done:

```bash
ccat stop
```

## 📖 Usage

### Basic Commands

| Command | Description | Example |
|---------|-------------|---------|
| `ccat start` | Start the Cheshire Cat server | `ccat start` |
| `ccat start -d` | Start in detached mode (background) | `ccat start -d` |
| `ccat stop` | Stop the server | `ccat stop` |
| `ccat update` | Update to the latest version | `ccat update` |

### Starting the Server

**Foreground mode** (see logs in real-time):
```bash
ccat start
```

**Background mode** (run in detached mode):
```bash
ccat start -d
```

**Skip cloud sync** when starting:
```bash
ccat start --no-sync
```

### Stopping the Server

```bash
ccat stop
```

Skip cloud sync when stopping:
```bash
ccat stop --no-sync
```

### Updating the Server

Keep your AI cat up to date with the latest features:
```bash
ccat update
```

## ☁️ Cloud Synchronization

Sync your cat's memory, plugins, and data across multiple machines using cloud storage!

### Setting Up Cloud Sync

Configure WebDAV or Nextcloud synchronization:

```bash
ccat sync configure webdav
```

You'll be prompted for:
- **WebDAV server URL**: Your cloud storage endpoint
  - Example: `https://cloud.example.com/remote.php/dav/files/username/`
- **Username**: Your cloud storage username
- **Password**: Your cloud storage password
- **Remote path**: Where to store data (default: `/ccat`)

### Cloud Sync Commands

| Command | Description |
|---------|-------------|
| `ccat sync configure webdav` | Configure WebDAV/Nextcloud sync |
| `ccat sync status` | Check sync configuration and status |
| `ccat sync now` | Manually trigger synchronization |
| `ccat sync disable` | Disable automatic cloud sync |

### Example: Setting Up Nextcloud Sync

```bash
$ ccat sync configure webdav
WebDAV server URL: https://nextcloud.example.com/remote.php/dav/files/myusername/
Username: myusername
Password: ********
Remote path [/ccat]: /cheshire-cat-backup

✓ Successfully configured webdav synchronization
Cloud sync will now run automatically when starting/stopping the server
```

### Checking Sync Status

```bash
$ ccat sync status
Cloud synchronization: ENABLED
Provider: webdav
Configuration:
  url: https://nextcloud.example.com/remote.php/dav/files/myusername/
  username: myusername
  remote_path: /cheshire-cat-backup
```

### Manual Sync

Manually sync your data at any time:

```bash
ccat sync now
```

## 🛠️ Troubleshooting

### Docker Not Running

If you see an error about Docker not being available:
```
Error: Docker is not running or not installed
```

**Solution**: Make sure Docker is installed and running:
```bash
# Check if Docker is running
docker ps

# Start Docker if needed (varies by OS)
sudo systemctl start docker  # Linux
# or open Docker Desktop on macOS/Windows
```

### Port Already in Use

If port 1865 is already in use, you can change it by setting the `CORE_PORT` environment variable:

```bash
export CORE_PORT=8080
ccat start
```

### Permission Issues

If you encounter permission issues with Docker:

```bash
# Add your user to the docker group (Linux)
sudo usermod -aG docker $USER

# Log out and back in for changes to take effect
```

## 🌐 Default Server URL

Once started, your Cheshire Cat server will be available at:
- **Admin Interface**: http://localhost:1865/admin
- **API Endpoint**: http://localhost:1865

## 📂 Data Storage

Your cat's data is stored locally in:
- **Linux/macOS**: `~/.local/share/ccat/`
- **Windows**: `%LOCALAPPDATA%\ccat\`

This includes:
- 🧠 Memory and conversation history
- 🔌 Installed plugins
- 📊 Configuration and data files
- 🐳 Docker Compose configuration

## 🤝 Contributing

Contributions are welcome! If you have ideas for improvements or find bugs:

1. Check the [issue tracker](https://github.com/matteospanio/cheshire-cat-cli/issues)
2. Open a new issue or submit a pull request
3. Help make this tool better for everyone! 🚀

## 🙏 Acknowledgements

Huge thanks to the amazing developers of the [Cheshire Cat AI](https://github.com/cheshire-cat-ai/core) project for creating such a fantastic AI framework!

## 📄 License

This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details.

---

<div align="center">

**Made with ❤️ for the Cheshire Cat AI community**

[Report Bug](https://github.com/matteospanio/cheshire-cat-cli/issues) • [Request Feature](https://github.com/matteospanio/cheshire-cat-cli/issues)

</div>