Skip to content

Commit 9753350

Browse files
nervebandnerveband
committed
Add comprehensive project summary documentation
1 parent 29137be commit 9753350

1 file changed

Lines changed: 243 additions & 0 deletions

File tree

‎PROJECT_SUMMARY.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# Beeper CLI - Project Summary
2+
3+
## Overview
4+
5+
A cross-platform command-line interface for the Beeper Desktop API, built in Go. Provides LLM-friendly interfaces for reading and sending messages across all Beeper-supported chat networks.
6+
7+
## Repository
8+
9+
**GitHub**: https://github.com/nerveband/beeper-cli
10+
11+
**Latest Release**: v0.1.0 - https://github.com/nerveband/beeper-cli/releases/tag/v0.1.0
12+
13+
## Architecture
14+
15+
### Technology Stack
16+
- **Language**: Go 1.22+
17+
- **CLI Framework**: Cobra
18+
- **Configuration**: Viper
19+
- **Build**: Native Go cross-compilation
20+
21+
### Project Structure
22+
```
23+
beeper-cli/
24+
├── main.go # Entry point
25+
├── cmd/ # CLI commands
26+
│ ├── root.go # Root command
27+
│ ├── discover.go # Auto-discovery
28+
│ ├── config.go # Configuration management
29+
│ ├── chats.go # Chat operations
30+
│ ├── messages.go # Message retrieval
31+
│ ├── send.go # Send messages
32+
│ └── search.go # Search messages
33+
├── internal/
34+
│ ├── api/ # API client
35+
│ │ └── client.go # HTTP client + models
36+
│ ├── config/ # Configuration
37+
│ │ └── config.go # Config management
38+
│ └── output/ # Output formatting
39+
│ └── formatter.go # JSON/text/markdown formatters
40+
├── examples/ # Usage examples
41+
│ ├── basic-usage.sh
42+
│ └── llm-integration.sh
43+
├── .github/workflows/ # CI/CD
44+
│ ├── build.yml # Build on push
45+
│ └── release.yml # Release on tag
46+
├── build.sh # Cross-compilation script
47+
├── README.md # Main documentation
48+
├── API.md # API documentation
49+
├── CONTRIBUTING.md # Contribution guide
50+
└── LICENSE # MIT License
51+
```
52+
53+
## Features
54+
55+
### Core Functionality
56+
✅ Auto-discover Beeper Desktop API endpoint
57+
✅ Configuration management (URL, output format)
58+
✅ List all chats with metadata
59+
✅ Get specific chat details
60+
✅ List messages from chats (with limit)
61+
✅ Send messages to chats
62+
✅ Search messages across all chats
63+
64+
### Output Formats
65+
- **JSON**: Structured data for LLM parsing
66+
- **Plain Text**: Human-readable output
67+
- **Markdown**: Formatted for documentation
68+
69+
### Cross-Platform Support
70+
- macOS (amd64, arm64)
71+
- Linux (amd64, arm64)
72+
- Windows (amd64)
73+
74+
## API Coverage
75+
76+
The CLI wraps the Beeper Desktop HTTP API:
77+
78+
| Endpoint | CLI Command | Status |
79+
|----------|-------------|--------|
80+
| `GET /health` | `discover` | ✅ Implemented |
81+
| `GET /chats` | `chats list` | ✅ Implemented |
82+
| `GET /chats/{id}` | `chats get` | ✅ Implemented |
83+
| `GET /chats/{id}/messages` | `messages list` | ✅ Implemented |
84+
| `POST /messages/send` | `send` | ✅ Implemented |
85+
| `GET /search` | `search` | ✅ Implemented |
86+
87+
## Usage Examples
88+
89+
### Basic Operations
90+
```bash
91+
# Auto-discover API
92+
beeper discover
93+
94+
# List chats
95+
beeper chats list
96+
97+
# Send message
98+
beeper send --chat-id CHAT_ID --message "Hello!"
99+
100+
# Search messages
101+
beeper search --query "important"
102+
```
103+
104+
### LLM Integration
105+
```bash
106+
# Extract chat IDs for processing
107+
beeper chats list | jq -r '.[] | .id'
108+
109+
# Find chats with unread messages
110+
beeper chats list | jq -r '.[] | select(.unread_count > 0)'
111+
112+
# Send and capture message ID
113+
MESSAGE_ID=$(beeper send --chat-id CHAT --message "Hi" | jq -r '.message_id')
114+
115+
# Export to markdown
116+
beeper messages list --chat-id CHAT --output markdown > messages.md
117+
```
118+
119+
## Development
120+
121+
### Build from Source
122+
```bash
123+
git clone https://github.com/nerveband/beeper-cli
124+
cd beeper-cli
125+
go build -o beeper .
126+
```
127+
128+
### Cross-Compile
129+
```bash
130+
./build.sh
131+
# Outputs to dist/ directory
132+
```
133+
134+
### Run Tests
135+
```bash
136+
go test ./...
137+
```
138+
139+
## CI/CD
140+
141+
### GitHub Actions Workflows
142+
143+
**Build Workflow** (`.github/workflows/build.yml`)
144+
- Triggers on push/PR to main
145+
- Runs on Ubuntu
146+
- Builds for all platforms
147+
- Runs tests
148+
149+
**Release Workflow** (`.github/workflows/release.yml`)
150+
- Triggers on version tags (v*)
151+
- Builds all platform binaries
152+
- Creates GitHub release
153+
- Uploads binaries as assets
154+
155+
### Creating a Release
156+
```bash
157+
git tag v0.2.0
158+
git push origin v0.2.0
159+
# GitHub Actions automatically builds and releases
160+
```
161+
162+
## Installation
163+
164+
### Pre-built Binaries
165+
Download from: https://github.com/nerveband/beeper-cli/releases/latest
166+
167+
```bash
168+
# macOS (arm64)
169+
curl -L https://github.com/nerveband/beeper-cli/releases/latest/download/beeper-darwin-arm64 -o beeper
170+
chmod +x beeper
171+
sudo mv beeper /usr/local/bin/
172+
173+
# Linux (amd64)
174+
curl -L https://github.com/nerveband/beeper-cli/releases/latest/download/beeper-linux-amd64 -o beeper
175+
chmod +x beeper
176+
sudo mv beeper /usr/local/bin/
177+
```
178+
179+
### From Source
180+
```bash
181+
go install github.com/nerveband/beeper-cli@latest
182+
```
183+
184+
## Configuration
185+
186+
Default config location: `~/.beeper-cli/config.yaml`
187+
188+
```yaml
189+
api_url: http://localhost:39867
190+
output_format: json # json, text, markdown
191+
```
192+
193+
## Requirements
194+
195+
- Beeper Desktop application running
196+
- API server enabled (default port: 39867)
197+
198+
## Comparison with Existing Tools
199+
200+
### vs. beeper-tools
201+
The existing [beeper-tools](https://github.com/beeper/beeper-tools):
202+
- ✅ Read-only (direct SQLite access)
203+
- ❌ Cannot send messages
204+
- ❌ No real-time operations
205+
206+
**This CLI**:
207+
- ✅ Read and write operations
208+
- ✅ Uses HTTP API (no database locks)
209+
- ✅ LLM-optimized output formats
210+
- ✅ Cross-platform binaries
211+
212+
## Future Enhancements
213+
214+
Potential additions:
215+
- [ ] React to messages
216+
- [ ] Edit messages
217+
- [ ] Delete messages
218+
- [ ] Mark messages as read
219+
- [ ] Get user information
220+
- [ ] Media upload/download
221+
- [ ] Typing indicators
222+
- [ ] Real-time message streaming (WebSocket)
223+
224+
## License
225+
226+
MIT License - See [LICENSE](LICENSE)
227+
228+
## Contributing
229+
230+
See [CONTRIBUTING.md](CONTRIBUTING.md)
231+
232+
## Links
233+
234+
- **Repository**: https://github.com/nerveband/beeper-cli
235+
- **Issues**: https://github.com/nerveband/beeper-cli/issues
236+
- **Releases**: https://github.com/nerveband/beeper-cli/releases
237+
- **Beeper Desktop**: https://www.beeper.com/
238+
239+
## Credits
240+
241+
Created by Ashraf Ali (@nerveband)
242+
243+
Built for LLM agents and power users who need programmatic access to Beeper.

0 commit comments

Comments
 (0)