session-cli 1.7.0

Python CLI tool and library for programmatic control of Session Desktop

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

MIT

Links

• Session Desktop
• PyPI
• GitHub