whispr-cli

A terminal interface for Whispr. Browse profiles, like matches, and chat in real time without leaving your terminal.

Table of Contents

• Overview
• Prerequisites
• Installation
• Configuration
• Authentication
• Commands
  • whispr config
  • whispr login
  • whispr logout
  • whispr whoami
  • whispr status
  • whispr discover
  • whispr matches
  • whispr likes
  • whispr chat
  • whispr views
  • whispr passed
  • whispr notifications
  • whispr profile
  • whispr version
• Premium Features
• Building from Source
• Publishing
• License

Overview

whispr-cli is a Node.js command-line client for the Whispr dating/matching platform. It provides a fully interactive terminal experience including:

• Browser-based authentication with automatic token refresh
• Interactive profile discovery with like, pass, and block actions
• Real-time chat with WebSocket-powered messaging, typing indicators, and delivery receipts
• Match, like, view, and notification management with JSON output support
• Pagination across all listing commands

Prerequisites

• Node.js >= 18
• A Whispr account (sign up via the web app)
• Access to a running Whispr API instance (self-hosted or the production service)

Installation

Install globally from npm:

npm install -g whispr-cli

Or run without installing:

npx whispr-cli

After installation, the whispr command is available in your terminal.

Authentication

whispr-cli uses a browser-based device flow. No password is ever typed into the terminal.

1. Run whispr login
2. A local callback server starts on a free port (5173-5202)
3. Your default browser opens to the Whispr web app login page
4. After you authenticate in the browser, the web app sends tokens back to the local server
5. Tokens are saved to ~/.config/whispr-cli/config.json

Access tokens are automatically refreshed on 401 responses. If the refresh fails, you are signed out and must run whispr login again.

If the API returns a 402 Payment Required, you will be prompted to upgrade your plan via the web app URL.

Commands

whispr login

Authenticate via browser. Opens the Whispr web app for login and stores tokens locally.

whispr login

If you are already logged in, the command verifies your existing session instead of opening a browser.

whispr logout

Sign out and remove stored tokens.

whispr logout

whispr whoami

Display the profile of the currently authenticated user.

whispr whoami

Shows: username, display name, email, onboarding status, and subscription plan.

whispr status

Show the full configuration and verify authentication.

whispr status

Shows: authentication state, username, onboarding status, and plan.

whispr discover

Browse profiles interactively. Profiles are fetched in batches and presented as full-screen cards in the terminal.

whispr discover [options]

| Option | Description | Default | | ----------------- | ------------------------------------- | ------- | | -l, --limit <n> | Number of profiles to fetch per batch | 10 |

Key bindings:

| Key | Action | | --------------- | ------------------------------------ | | L | Like (or unlike if already liked) | | N or → | Next profile | | Z or ← | Previous profile (from history) | | P | Pass (permanently hide this profile) | | B | Block user (requires confirmation) | | Q or Ctrl-C | Quit |

Each profile card shows: online indicator, username, age, career, location, bio, interests, relationship type, and compatibility percentage. Profiles you have already liked are flagged with a badge.

When a mutual match occurs, the terminal displays a "It's a match!" message and suggests opening a chat.

whispr matches

List your current matches.

whispr matches [options]

| Option | Description | Default | | --------------- | ---------------------------------- | ------- | | --output json | Output raw JSON instead of a table | - | | --page <n> | Page number | 1 | | --limit <n> | Results per page | 20 |

Displays a table with: username, age, career, when you matched, and unread message count.

Unmatch a user:

whispr matches unmatch <username>

The @ prefix is optional. Looks up the user by username from your matches list, prompts for confirmation, then removes the match and deletes the chat history.

whispr likes

Manage likes sent and received.

Likes you have sent:

whispr likes sent [options]

Likes you have received:

whispr likes received [options]

After displaying the table, prompts you to like someone back by entering their list number.

Dismissed likes (Premium):

whispr likes dismissed [options]

All likes subcommands share the same options:

| Option | Description | Default | | --------------- | ---------------- | ------- | | --output json | Output raw JSON | - | | --page <n> | Page number | 1 | | --limit <n> | Results per page | 20 |

whispr chat

Manage and open conversations.

List all conversations:

whispr chat

Displays a table with: online status, username, last message preview, time, and unread count. Prompts you to select a conversation by number to open it.

Start a new chat with a match:

whispr chat start <username>

The @ prefix is optional. Both @alice and alice work. Creates or retrieves the existing chat and opens the interactive session.

Open a chat by ID:

whispr chat open <chatId>

Interactive chat session:

Once a chat is open, you are in a live session:

• Type a message and press Enter to send
• Press Ctrl-C to exit
• Incoming messages appear in real time
• Typing indicators show when the other person is composing
• Message status ticks: ~ sent, * delivered, ** read
• Online/offline presence updates are shown inline

whispr views

(Premium feature) See who has viewed your profile.

whispr views [options]

| Option | Description | Default | | --------------- | ---------------- | ------- | | --output json | Output raw JSON | - | | --page <n> | Page number | 1 | | --limit <n> | Results per page | 20 |

Displays: username, age, career, view count, last seen. Profiles that have already liked you are highlighted. Prompts to like someone back interactively.

whispr passed

(Premium feature) View profiles you have passed on.

whispr passed [options]

| Option | Description | Default | | --------------- | ---------------- | ------- | | --output json | Output raw JSON | - | | --page <n> | Page number | 1 | | --limit <n> | Results per page | 20 |

Displays: username, age, career, when passed. Prompts to like someone from the list interactively.

whispr notifications

View and manage notifications.

List notifications:

whispr notifications [options]

| Option | Description | Default | | --------------- | ---------------- | ------- | | --output json | Output raw JSON | - | | --page <n> | Page number | 1 | | --limit <n> | Results per page | 20 |

Unread notifications are highlighted. If unread notifications are present, prompts to mark all as read.

Notification statistics:

whispr notifications stats

Shows total and unread counts, broken down by type (LIKE, MATCH, MESSAGE, SECURITY, ADMIN, SUBSCRIPTION).

Mark all notifications as read:

whispr notifications read

Delete all notifications:

whispr notifications clear

Prompts for confirmation before deleting.

whispr profile

View a user's public profile.

whispr profile <username>

The @ prefix is optional. Displays all available public fields: username, age, gender, location, career, education, height, personality type, relationship intent, lifestyle (smoking/drinking), interests, and bio. Fields that are unset are omitted.

whispr version

Display version information.

whispr version

Shows: whispr-cli version, Node.js version, and operating system platform.

Premium Features

The following commands require an active Whispr premium subscription:

| Command | Description | | ------------------------ | --------------------------------------- | | whispr likes dismissed | See likes you have previously dismissed | | whispr views | See who has viewed your profile | | whispr passed | Revisit profiles you passed on |

If you attempt a premium action without a subscription, you will be prompted to upgrade via the web app.

License

Copyright © Whispr. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, in whole or in part, is strictly prohibited.