calm-client 0.1.0

Async Python client for Calm.com internal API

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:

# Core CLI (login, search, whoami)
pipx install calm-client

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

Library

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

pip install calm-client

Requirements

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

• mpv — Required for calm play and calm browse audio features

  # Ubuntu/Debian
  sudo apt install mpv
  
  # 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("[e-mail]", "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