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

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)

Source distribution for session-cli 1.7.0
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)

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

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