# 🐦 ssky - Simple Bluesky Client
A lightweight, command-line Bluesky client that makes it easy to interact with the Bluesky social network from your terminal.
## ✨ Features
- 🔑 Simple authentication and session management
- 📝 Post, reply, quote, and repost content
- 🔍 Search posts and users
- 👥 Follow/unfollow users
- 📊 View timelines and profiles
- 🖼️ Support for images and link cards
- 📦 Linux shell friendly output formats
## 🚀 Quick Start
### Installation
```bash
pip install ssky
```
### Login
```bash
ssky login your-handle.bsky.social:your-password
```
Or set credentials via environment variable:
```bash
export SSKY_USER=your-handle.bsky.social:your-password
```
## 📖 Basic Usage
### Posting
```bash
# Simple post
ssky post "Hello, Bluesky!"
# Post with images
ssky post "Check out these photos!" --image photo1.jpg --image photo2.jpg
# Reply to a post
ssky post "Great post!" --reply-to at://did:plc:.../app.bsky.feed.post/...
# Quote a post
ssky post "Interesting!" --quote at://did:plc:.../app.bsky.feed.post/...
```
### Reading
```bash
# View your timeline
ssky get
# View someone's profile
ssky profile user.bsky.social
# Search posts
ssky search "keyword"
# Search users
ssky user "username"
```
### Social Actions
```bash
# Follow a user
ssky follow user.bsky.social
# Repost a post
ssky repost at://did:plc:.../app.bsky.feed.post/...
# Delete a post
ssky delete at://did:plc:.../app.bsky.feed.post/...
```
## 🔧 Advanced Usage
### Output Formats
```bash
# Get only post IDs
ssky get --id
# Get only text content
ssky get --text
# Get full JSON output
ssky get --json
# Save posts to files
ssky get --output ./posts
```
### Useful Examples
```bash
# Reply to your last post
ssky post "Update!" --reply-to $(ssky get myself --limit 1 --id)
# Search your own posts
ssky search "keyword" --author myself
# Save your timeline to files
ssky get --output ./timeline
```
## 🤖 IDE Integration
### Cursor Agent MCP Tools
`ssky` provides comprehensive MCP (Model Context Protocol) tools for seamless integration with Cursor Agent, enabling AI-powered Bluesky interactions directly in your development environment.
**Features:**
- 📋 **10 comprehensive tools**: Complete Bluesky functionality
- 🤖 **AI-optimized**: Long format defaults for better AI understanding
- 🔧 **Full feature support**: Posts with images, quotes, replies, search, social actions
- ⚡ **Real-time integration**: Direct Bluesky interaction from Cursor
**Quick Setup:**
```bash
# For new MCP setup: copy sample configuration (no build required!)
mkdir -p .cursor
cp mcp/mcp.sample.json .cursor/mcp.json
# Set your Bluesky credentials
export SSKY_USER=your-handle.bsky.social:your-password
# Restart Cursor to load the MCP tools
```
✨ **Docker will automatically pull the pre-built image on first use!**
**Advanced Setup:**
- **For existing MCP setup**: Add ssky server to your `.cursor/mcp.json` (see `mcp/mcp.sample.json`)
- **For local development**: Use `cd mcp && ./build.sh && cd ..` to build locally
- **Complete guide**: See [MCP Documentation](mcp/SSKY_MCP_GUIDE.md)
**Available Tools:**
- `ssky_get`, `ssky_search`, `ssky_user`, `ssky_profile` - Content retrieval
- `ssky_post` - Content creation with images/quotes/replies
- `ssky_follow`, `ssky_unfollow`, `ssky_repost`, `ssky_unrepost` - Social actions
- `ssky_delete` - Content management
📖 **[Complete MCP Documentation](mcp/SSKY_MCP_GUIDE.md)**
## 🧪 Testing
To run the tests in the `tests/` directory:
1. Copy the environment configuration file and set your Bluesky credentials:
```bash
cp tests/_env tests/.env
```
Edit `tests/.env` and add your Bluesky handle and password.
2. Run tests using pytest:
```bash
# Run all tests
pytest tests/ -v
# Run individual feature tests
pytest tests/test_login.py -v # Login functionality
pytest tests/test_post_and_delete.py -v # Post and delete operations
pytest tests/test_search.py -v # Search functionality
pytest tests/test_follow_unfollow.py -v # Follow/unfollow operations
pytest tests/test_get.py -v # Timeline retrieval
pytest tests/test_profile.py -v # Profile display
pytest tests/test_repost_unrepost.py -v # Repost/unrepost operations
pytest tests/test_user.py -v # User functionality
```
## 📝 Requirements
- Python 3.12 or later
## 📜 License
[MIT License](LICENSE)
## 👥 Author
[SimpleSkyClient Project](https://github.com/simpleskyclient)
Raw data
{
"_id": null,
"home_page": "https://github.com/simpleskyclient/ssky",
"name": "ssky",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.12",
"maintainer_email": null,
"keywords": "bluesky, client",
"author": "SimpleSkyClient Project",
"author_email": "simpleskypclient@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a2/59/eb7bf3e9d38ac3982afdef6c37d79927844aa546c32a51c18f95524144c5/ssky-0.2.4.tar.gz",
"platform": null,
"description": "# \ud83d\udc26 ssky - Simple Bluesky Client\n\nA lightweight, command-line Bluesky client that makes it easy to interact with the Bluesky social network from your terminal.\n\n## \u2728 Features\n\n- \ud83d\udd11 Simple authentication and session management\n- \ud83d\udcdd Post, reply, quote, and repost content\n- \ud83d\udd0d Search posts and users\n- \ud83d\udc65 Follow/unfollow users\n- \ud83d\udcca View timelines and profiles\n- \ud83d\uddbc\ufe0f Support for images and link cards\n- \ud83d\udce6 Linux shell friendly output formats\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install ssky\n```\n\n### Login\n\n```bash\nssky login your-handle.bsky.social:your-password\n```\n\nOr set credentials via environment variable:\n```bash\nexport SSKY_USER=your-handle.bsky.social:your-password\n```\n\n## \ud83d\udcd6 Basic Usage\n\n### Posting\n\n```bash\n# Simple post\nssky post \"Hello, Bluesky!\"\n\n# Post with images\nssky post \"Check out these photos!\" --image photo1.jpg --image photo2.jpg\n\n# Reply to a post\nssky post \"Great post!\" --reply-to at://did:plc:.../app.bsky.feed.post/...\n\n# Quote a post\nssky post \"Interesting!\" --quote at://did:plc:.../app.bsky.feed.post/...\n```\n\n### Reading\n\n```bash\n# View your timeline\nssky get\n\n# View someone's profile\nssky profile user.bsky.social\n\n# Search posts\nssky search \"keyword\"\n\n# Search users\nssky user \"username\"\n```\n\n### Social Actions\n\n```bash\n# Follow a user\nssky follow user.bsky.social\n\n# Repost a post\nssky repost at://did:plc:.../app.bsky.feed.post/...\n\n# Delete a post\nssky delete at://did:plc:.../app.bsky.feed.post/...\n```\n\n## \ud83d\udd27 Advanced Usage\n\n### Output Formats\n\n```bash\n# Get only post IDs\nssky get --id\n\n# Get only text content\nssky get --text\n\n# Get full JSON output\nssky get --json\n\n# Save posts to files\nssky get --output ./posts\n```\n\n### Useful Examples\n\n```bash\n# Reply to your last post\nssky post \"Update!\" --reply-to $(ssky get myself --limit 1 --id)\n\n# Search your own posts\nssky search \"keyword\" --author myself\n\n# Save your timeline to files\nssky get --output ./timeline\n```\n\n## \ud83e\udd16 IDE Integration\n\n### Cursor Agent MCP Tools\n\n`ssky` provides comprehensive MCP (Model Context Protocol) tools for seamless integration with Cursor Agent, enabling AI-powered Bluesky interactions directly in your development environment.\n\n**Features:**\n- \ud83d\udccb **10 comprehensive tools**: Complete Bluesky functionality\n- \ud83e\udd16 **AI-optimized**: Long format defaults for better AI understanding \n- \ud83d\udd27 **Full feature support**: Posts with images, quotes, replies, search, social actions\n- \u26a1 **Real-time integration**: Direct Bluesky interaction from Cursor\n\n**Quick Setup:**\n```bash\n# For new MCP setup: copy sample configuration (no build required!)\nmkdir -p .cursor\ncp mcp/mcp.sample.json .cursor/mcp.json\n\n# Set your Bluesky credentials\nexport SSKY_USER=your-handle.bsky.social:your-password\n\n# Restart Cursor to load the MCP tools\n```\n\n\u2728 **Docker will automatically pull the pre-built image on first use!**\n\n**Advanced Setup:**\n- **For existing MCP setup**: Add ssky server to your `.cursor/mcp.json` (see `mcp/mcp.sample.json`)\n- **For local development**: Use `cd mcp && ./build.sh && cd ..` to build locally\n- **Complete guide**: See [MCP Documentation](mcp/SSKY_MCP_GUIDE.md)\n\n**Available Tools:**\n- `ssky_get`, `ssky_search`, `ssky_user`, `ssky_profile` - Content retrieval\n- `ssky_post` - Content creation with images/quotes/replies\n- `ssky_follow`, `ssky_unfollow`, `ssky_repost`, `ssky_unrepost` - Social actions\n- `ssky_delete` - Content management\n\n\ud83d\udcd6 **[Complete MCP Documentation](mcp/SSKY_MCP_GUIDE.md)**\n\n## \ud83e\uddea Testing\n\nTo run the tests in the `tests/` directory:\n\n1. Copy the environment configuration file and set your Bluesky credentials:\n ```bash\n cp tests/_env tests/.env\n ```\n Edit `tests/.env` and add your Bluesky handle and password.\n\n2. Run tests using pytest:\n ```bash\n # Run all tests\n pytest tests/ -v\n \n # Run individual feature tests\n pytest tests/test_login.py -v # Login functionality\n pytest tests/test_post_and_delete.py -v # Post and delete operations\n pytest tests/test_search.py -v # Search functionality\n pytest tests/test_follow_unfollow.py -v # Follow/unfollow operations\n pytest tests/test_get.py -v # Timeline retrieval\n pytest tests/test_profile.py -v # Profile display\n pytest tests/test_repost_unrepost.py -v # Repost/unrepost operations\n pytest tests/test_user.py -v # User functionality\n ```\n\n## \ud83d\udcdd Requirements\n\n- Python 3.12 or later\n\n## \ud83d\udcdc License\n\n[MIT License](LICENSE)\n\n## \ud83d\udc65 Author\n\n[SimpleSkyClient Project](https://github.com/simpleskyclient)\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "Simple bluesky client",
"version": "0.2.4",
"project_urls": {
"Homepage": "https://github.com/simpleskyclient/ssky",
"Repository": "https://github.com/simpleskyclient/ssky"
},
"split_keywords": [
"bluesky",
" client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ab08fb0edb23f0ab02ed846eb5a1e4e99049b95d6aad01628bb23b522647d5b5",
"md5": "36b06c9162399279864cf49cafddbc8b",
"sha256": "2e29b5f5cba4aa1db72591b1baea9bf83542f314a21e11fdc3c006481e50d9d5"
},
"downloads": -1,
"filename": "ssky-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36b06c9162399279864cf49cafddbc8b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.12",
"size": 30771,
"upload_time": "2025-08-03T06:43:42",
"upload_time_iso_8601": "2025-08-03T06:43:42.634623Z",
"url": "https://files.pythonhosted.org/packages/ab/08/fb0edb23f0ab02ed846eb5a1e4e99049b95d6aad01628bb23b522647d5b5/ssky-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a259eb7bf3e9d38ac3982afdef6c37d79927844aa546c32a51c18f95524144c5",
"md5": "8aaf6833ea2520d3823fe0ce146d7f77",
"sha256": "e7f3b417626a1801d1d02ffa35c49591b28687f23482c262d8f8e93271baf1e6"
},
"downloads": -1,
"filename": "ssky-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "8aaf6833ea2520d3823fe0ce146d7f77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.12",
"size": 23966,
"upload_time": "2025-08-03T06:43:43",
"upload_time_iso_8601": "2025-08-03T06:43:43.665730Z",
"url": "https://files.pythonhosted.org/packages/a2/59/eb7bf3e9d38ac3982afdef6c37d79927844aa546c32a51c18f95524144c5/ssky-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 06:43:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "simpleskyclient",
"github_project": "ssky",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ssky"
}
JSON
