OpenMates Docs Open Chat

OpenMates CLI

OpenMates CLI A terminal interface and Node.js SDK for interacting with OpenMates. Plain opens a lightweight chat TUI in interactive terminals; explicit subc...

[T:documentation.sender_name]

OpenMates CLI

A terminal interface and Node.js SDK for interacting with OpenMates. Plain openmates opens a lightweight chat TUI in interactive terminals; explicit subcommands provide pair-auth login, encrypted chat operations, app skill execution, settings management, and self-hosted server administration.

Installation

npm install -g openmates
openmates

Requires Node.js 20+. Runtime dependencies are minimal: qrcode-terminal (pair-auth QR display), ws (WebSocket streaming), @toon-format/toon (embed encoding), and ahocorasick (mention matching).

Quick Start

openmates
openmates login
openmates whoami
openmates chats list
openmates chats show example-gigantic-airplanes
openmates chats new "Hello, what can you help me with?"
openmates chats new "Review @./src/app.ts"
openmates apps list

In a normal terminal, plain openmates enters the full-screen chat UI. Use /examples for public examples, /help for TUI commands, /login for pair-auth, /signup to leave the TUI and run guided account creation, and /exit to restore your shell. In redirected or piped contexts, plain openmates prints common programmatic commands and exits successfully.

openmates chats list, show, and open work before login for clearly labeled public example chats. Private encrypted chats, settings, and personalized data require login. Login uses pair-auth – the CLI never asks for your account password during login. A QR code or pair PIN is displayed in your terminal, which you confirm in the web app. New users can run openmates signup for guided account creation. See authentication.md for details.

Commands

Category Description Doc
signup, login, logout, whoami Account creation, authentication, and session authentication.md
chats List, search, show, send, share, download, delete, incognito chats.md
apps List apps, run skills, view skill info apps-and-skills.md
settings, learning-mode Predefined settings commands, Learning Mode controls, invoices, notifications, mates, newsletter, memories settings.md
benchmark Run real product-path model benchmarks, comparisons, and judged case suites benchmarks.md
embeds, mentions View embeds, create share links, search mentions embeds-and-sharing.md
remote-access Attach and search local Project sources without uploading repository files remote-access.md
inspirations, newchatsuggestions Daily inspirations and personalized suggestions chats.md
docs Browse, search, show, and download documentation docs.md
server Install, start, stop, update a self-hosted instance server-management.md

Global Flags

Flag Description
--json Output raw JSON instead of formatted output
--api-url <url> Override API base URL (default: https://api.openmates.org)
--api-key <key> Optional API key override (or set OPENMATES_API_KEY env var)
--help Show contextual help for any command

Configuration

Session data is stored in ~/.openmates/:

File Purpose
session.json Authentication session token
sync_cache.json Cached decrypted data for offline access
server.json Self-hosted server configuration

All files are created with strict permissions (0o600 owner read/write only, directory 0o700). See authentication.md for security details.

Key Files

  • See cli.ts for the command entry point and argument router
  • See client.ts for the SDK client and all API operations
  • See server.ts for server management commands