https://github.com/confy-security/cli
CLI client for the Confy encrypted communication system
https://github.com/confy-security/cli
chat chat-application chat-cli cli confy prompt-toolkit typer websocket
Last synced: 5 months ago
JSON representation
CLI client for the Confy encrypted communication system
- Host: GitHub
- URL: https://github.com/confy-security/cli
- Owner: confy-security
- License: gpl-3.0
- Created: 2025-03-31T15:05:31.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-24T11:29:29.000Z (5 months ago)
- Last Synced: 2026-01-24T22:11:21.914Z (5 months ago)
- Topics: chat, chat-application, chat-cli, cli, confy, prompt-toolkit, typer, websocket
- Language: Python
- Homepage:
- Size: 404 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
Confy CLI
A command-line client for the Confy encrypted communication system.
[](https://github.com/confy-security/cli/actions/workflows/test.yml)
[](https://pypi.org/project/confy-cli/)
[](https://aur.archlinux.org/packages/confy-cli)
[](https://pypi.org/project/confy-cli/)
[](/LICENSE)
[](https://github.com/confy-security/cli)
---
A secure command-line interface for peer-to-peer encrypted messaging using the Confy communication system. This CLI enables users to establish encrypted connections with other peers, exchange cryptographic keys, and communicate with end-to-end encryption using industry-standard algorithms.
Learn more about the project at [github.com/confy-security](https://github.com/confy-security)
Made with dedication by students from Brazil 🇧🇷.
## ⚡ Features
- **End-to-End Encryption** - Messages are encrypted using AES-256 in CFB mode
- **Digital Signatures** - Messages are signed using RSA with PSS padding for authenticity
- **Secure Key Exchange** - RSA-4096 key exchange with OAEP padding
- **Interactive Terminal** - User-friendly command-line interface using prompt-toolkit and Typer
- **Debug Mode** - Detailed logging for troubleshooting and development
- **Cross-Platform** - Works on Windows, macOS, and Linux
- **WebSocket Support** - Secure peer-to-peer communication over WebSocket (WSS)
## ⚙️ Requirements
- **Python:** 3.13 or higher
- **OS:** Windows, macOS, or Linux
## 📦 Installation
Install the CLI globally with your Python package manager of choice.
```shell
pipx install confy-cli
```
### With AUR (Arch Linux)
You can install the CLI from the AUR using an AUR helper like `yay`:
```bash
yay -S confy-cli
```
### 🐳 Using Docker
Alternatively, you can use the CLI via a Docker container:
```bash
docker run -it ghcr.io/confy-security/cli:latest
```
Once inside the container, you can use the CLI normally:
```bash
confy start your-user-id recipient-user-id
```
To build the Docker image locally:
```bash
docker build -t confy-cli .
docker run -it confy-cli
```
## 🚀 Quick Start
### Basic Usage
Start a secure conversation with another peer:
```bash
confy start your-user-id recipient-user-id
```
When prompted, enter the server address:
```txt
Server address: wss://secure-server.example.com
```
> [!TIP]
> To learn how to deploy your own self-hosted Confy server, see [github.com/confy-security/server](https://github.com/confy-security/server).
### Interactive Commands
Once connected, you can:
- **Send messages** - Type your message and press Enter
- **Receive messages** - Messages from peers appear in real-time
- **Exit** - Type `exit` to end the session
### Example Session
```bash
$ confy start alice bob
Server address: wss://secure-server.example.com
[SYSTEM] Waiting for recipient to connect...
[SYSTEM] The recipient is now connected.
> Hello Bob, this is Alice!
[RECEIVED] Hi Alice! I received your message.
> exit
```
## 🔒 Security Architecture
### Key Exchange Process
1. **RSA Key Generation** - Each client generates a 4096-bit RSA key pair
2. **Public Key Exchange** - Public keys are exchanged securely over WebSocket
3. **AES Key Generation** - A random 256-bit AES key is generated
4. **Encrypted Key Distribution** - AES key is encrypted with peer's RSA public key
5. **Secure Communication** - All messages are encrypted with the shared AES key and signed
### Encryption Details
- **Message Encryption** - AES-256 in CFB mode
- **Key Encryption** - RSA-4096 with OAEP padding
- **Signatures** - RSA-4096 with PSS padding and SHA-256
- **Cryptography Library** - Uses the `cryptography` library (actively maintained)
## 📚 Environment Variables
Configure the CLI using environment variables:
```bash
# Enable debug mode
export DEBUG=true
# Or set it in .env file
DEBUG=false
```
Create a `.env` file in your project directory:
```env
DEBUG=false
```
## 🔧 Configuration
### Server Address Format
The server address can be specified as:
- **Secure WebSocket** - `wss://example.com` (recommended)
- **WebSocket** - `ws://example.com` (use only for testing)
- **HTTPS** - `https://example.com` (automatically converts to WSS)
- **HTTP** - `http://example.com` (automatically converts to WS)
### Connection History
The CLI stores your connection history in:
```txt
~/.confy_address_history
```
This allows you to quickly access previously used server addresses using arrow keys.
## 🛠️ Troubleshooting
### Connection Issues
**"Error connecting to server"**
- Verify the server address is correct
- Ensure the server is running and accessible
- Check your network connectivity
- For WSS connections, verify the SSL certificate is valid
**"Connection refused"**
- Confirm the server is listening on the specified address and port
- Check if a firewall is blocking the connection
### Message Issues
**"AES key has not been established yet"**
- Wait a moment for the key exchange to complete
- Ensure both peers are connected
- Check if the server is properly relaying messages
**"Failed to encrypt/verify message"**
- This indicates an issue with the encryption layer
- Try reconnecting to the server
- Check if both peers are running compatible CLI versions
### Performance Issues
**Slow response times**
- Check your network latency to the server
- Consider using a server closer to your location
- Reduce the frequency of large messages
## 📖 Usage Guide
### Connecting to a Server
```bash
confy start alice bob
```
You'll be prompted to enter the server address. For the first time, you can enter:
```txt
Server address: wss://secure-server.example.com
```
### Sending Messages
Simply type your message and press Enter:
```txt
> Your encrypted message here
```
### Security Considerations
1. **Verify Recipients** - Ensure you're communicating with the intended person
2. **Secure Connections** - Always use WSS (WebSocket Secure) in production
3. **Key Management** - Store your user ID securely
4. **Session Management** - End sessions with `exit` when finished
### Advanced Usage
#### Debug Mode
Enable debug mode to see detailed information:
```bash
DEBUG=true confy start alice bob
```
This will display:
- Key exchange details
- Message encryption/decryption info
- Connection status changes
- Signature verification steps
#### Custom Server
Connect to a custom server:
```bash
confy start your-id recipient-id
Server address: wss://your-custom-server.com:8080
```
## 🤝 Dependencies
Confy CLI relies on:
- **[typer](https://typer.tiangolo.com/)** (>=0.15.4, <0.16.0) - CLI framework
- **[websockets](https://websockets.readthedocs.io/)** (>=15.0.1, <16.0.0) - WebSocket protocol support
- **[pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)** (>=2.11.0, <3.0.0) - Configuration management
- **[confy-addons](https://github.com/confy-security/confy-addons)** (>=1.1.0, <2.0.0) - Encryption primitives
- **[prompt-toolkit](https://python-prompt-toolkit.readthedocs.io/)** (>=3.0.52, <4.0.0) - Terminal interface
All dependencies are installed automatically with pip.
## 🐛 Bug Reports
If you encounter any issues, please report them:
1. Check if the issue already exists on [GitHub Issues](https://github.com/confy-security/cli/issues)
2. Provide clear reproduction steps
3. Include your Python version and OS
4. Attach relevant logs with `DEBUG=true`
See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
## 🔐 Security Policy
For security vulnerabilities, please follow responsible disclosure:
**DO NOT** open a public GitHub issue.
Instead, email: [confy@henriquesebastiao.com](mailto:confy@henriquesebastiao.com)
See [SECURITY.md](SECURITY.md) for detailed information.
## 📝 Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
- Setting up the development environment
- Code standards and style guidelines
- Testing requirements
- Pull request process
## 📄 License
Confy CLI is open source software licensed under the [GPL-3.0](https://github.com/confy-security/cli/blob/main/LICENSE) license.
## 📚 Additional Resources
- **Confy Security** - [github.com/confy-security](https://github.com/confy-security)
- **Contributing Guide** - [CONTRIBUTING.md](CONTRIBUTING.md)
- **Security Policy** - [SECURITY.md](SECURITY.md)
- **Code of Conduct** - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
## 🙋 Support
For questions and support:
- Check existing issues and discussions on GitHub
- Review the [CONTRIBUTING.md](CONTRIBUTING.md) guide
- Contact the team at [confy@henriquesebastiao.com](mailto:confy@henriquesebastiao.com)
## Acknowledgments
This project was created with dedication by Brazilian students 🇧🇷 as part of the Confy Security initiative.
**Built with ❤️ by the Confy Security Team**