Session CLI
A Python CLI tool and library for programmatic control of Session Desktop, the privacy-focused messenger.
Features
- Read-only database access - Query messages, conversations, and attachments from Session's SQLCipher database
- CDP control - Send messages and manage groups via Chrome DevTools Protocol
- MCP server - Expose Session data to AI agents (Claude Desktop, Claude Code)
- Full-text search - Search messages with date, sender, and type filters
- Export & backup - Export to JSON/CSV/HTML, encrypted backups
- Interactive REPL - Persistent session with tab completion
- Cross-platform - macOS and Linux
Installation
pip install session-cli
Requires Python 3.10+ and Session Desktop (run at least once to create the database).
Quick Start
# See all commands
session-cli -h
# List conversations
session-cli list
# View messages
session-cli messages <conversation_id>
# Search messages
session-cli search "keyword" --after 7d
# Interactive mode
session-cli repl
Sending Messages (requires CDP)
Start Session with remote debugging:
# macOS
/Applications/Session.app/Contents/MacOS/Session --remote-debugging-port=9222 --remote-allow-origins="*"
# Linux
session-desktop --remote-debugging-port=9222 --remote-allow-origins="*"
Then send:
session-cli send <conversation_id> "Hello!"
Python API
from session_controller import SessionDatabase, SessionCDP
# Read messages (offline)
with SessionDatabase() as db:
for convo in db.get_conversations():
print(f"{convo.name}: {convo.last_message}")
messages = db.get_messages(convo.id, limit=10)
results = db.search_messages("keyword")
# Send messages (requires Session running with CDP)
with SessionCDP(port=9222) as cdp:
cdp.send_message("05abc123...", "Hello!")
MCP Server
Expose Session data to AI agents via Model Context Protocol.
session-mcp
Claude Desktop / Claude Code
Add to your MCP config:
{
"mcpServers": {
"session": {
"command": "session-mcp"
}
}
}
Config locations:
- Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json(macOS) or~/.config/Claude/claude_desktop_config.json(Linux) - Claude Code:
.claude/settings.json
Once configured, ask Claude things like "List my Session conversations" or "Search my messages for 'meeting' from last week".
Configuration
Save defaults in ~/.config/session-cli/config.yaml (Linux) or ~/Library/Application Support/session-cli/config.yaml (macOS):
profile: null
port: 9222
json: false
commands:
messages:
limit: 50
Data Locations
- macOS:
~/Library/Application Support/Session/ - Linux:
~/.config/Session/
Limitations
- Database is read-only (prevents corruption)
- Sending messages/managing groups requires CDP
- Windows not supported yet
License
Links
Release files for session-cli 1.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| session_cli-1.7.0.tar.gz | 58.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| session_cli-1.7.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 112.6 kB
Release files / session_cli-1.7.0.tar.gz
| Download URL | session_cli-1.7.0.tar.gz |
|---|---|
| Size | 58.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2cc23aad32593366fc105143e25a5266890113cc9199f2b35fd94cf5cdc39568
|
|
BLAKE2b-256 checksum How to use checksums |
e5b0f2ad5ed4fb9096cd8e2110c081842ef075318ae10ef1a35faa398b5177a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.12
|
Release files / session_cli-1.7.0-py3-none-any.whl
| Download URL | session_cli-1.7.0-py3-none-any.whl |
|---|---|
| Size | 54.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
79701609a98b359f66c617aa7f1c55d5522f2061b686042b1d8d53c994c8ec63
|
|
BLAKE2b-256 checksum How to use checksums |
de3a6e061178585854ab9418cb025780f19e948e9912d0dae908ad2af5cd6fea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.12
|