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
Metadata
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 | Provenance | Actions |
|---|---|---|---|---|
| session_cli-1.7.0.tar.gz | 58.4 kB | Without provenance | Details for session_cli-1.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| session_cli-1.7.0-py3-none-any.whl | Python 3 | none | any | Details for session_cli-1.7.0-py3-none-any.whl |
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
|
Security for session-cli 1.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.