---

🎯 What is Cheshire Cat CLI?

The Cheshire Cat CLI is a command-line interface tool that simplifies the management of your Cheshire Cat AI 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:

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:

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

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):

ccat start

Background mode (run in detached mode):

ccat start -d

Skip cloud sync when starting:

ccat start --no-sync

Stopping the Server

ccat stop

Skip cloud sync when stopping:

ccat stop --no-sync

Updating the Server

Keep your AI cat up to date with the latest features:

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:

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

$ 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

$ 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:

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:

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

export CORE_PORT=8080
ccat start

Permission Issues

If you encounter permission issues with Docker:

# 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
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 project for creating such a fantastic AI framework!

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

---