Calm Client (Python)

Async Python client and CLI for the internal Calm.com API. Browse the catalog, search for content, and stream audio — all from your terminal.

Features

• CLI + TUI — Browse, search, and play Calm content from the terminal
• Async API — Fully async Python client built on httpx
• Type Safe — Comprehensive Pydantic models with py.typed support
• Audio Playback — Stream meditation and sleep audio via mpv
• Auth — Email/password login with automatic token refresh

Installation

CLI (recommended)

Use pipx to install the CLI in an isolated environment with zero hassle — no virtualenv management needed:

# Full CLI with audio playback (play, browse) — needs mpv, see Requirements
pipx install 'calm-client[player]'

# CLI and TUI browser without audio playback (login, search, whoami, browse)
pipx install 'calm-client[cli]'

Library

If you want to use calm-client as a Python library in your own project:

pip install calm-client

The plain package installs only the API client and its few dependencies (httpx, pydantic, structlog). The cli and player extras add the terminal UI and audio playback.

Requirements

• Python 3.12+ - for modern typing, async, and f-strings

• mpv — Required for calm play and calm browse audio features (the player extra loads mpv's libmpv library)

  # Ubuntu/Debian
  sudo apt install mpv libmpv-dev
  
  # macOS
  brew install mpv
  
  # Arch
  sudo pacman -S mpv
  

Quick Start (CLI)

# 1. Login
calm login

# 2. Browse interactively
calm browse

# 3. Or search and play directly
calm search "Sleep Stories"
calm play <program_id>

Quick Start (Python)

import asyncio
from calm_client import CalmClient


async def main():
    async with CalmClient() as client:
        # Authenticate
        await client.login("email@example.com", "password")

        # Get the Sleep feed
        feed = await client.get_feed("sleep")
        print(f"Found {len(feed.items)} items")

        # Search
        results = await client.search("Rain")
        print(f"Found {len(results.items)} results")


if __name__ == "__main__":
    asyncio.run(main())

Documentation

• CLI Reference — Commands, options, and TUI controls
• Library Reference — Python API, classes, and models

Development

See CONTRIBUTING.md for the full development setup.

# Quick start
uv sync --all-extras --all-groups
uv run hatch test
uv run hatch fmt

License

MIT