Skip to main content

Session CLI

PyPI version Python versions License

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

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)

Source distribution for session-cli 1.7.0
File Size Uploaded
session_cli-1.7.0.tar.gz 58.4 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for session-cli 1.7.0
File Interpreter ABI Platform
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

Release history Release notifications | RSS feed

This release

1.7.0 This release

2 release files

1.6.0

2 release files

1.5.2

2 release files

1.5.1

2 release files

1.5.0

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page