Metadata-Version: 2.5
Name: circle-chat
Version: 0.3.2
Summary: Chat with your circle of friends, entirely in the terminal.
Project-URL: Repository, https://github.com/bgaibull/circle
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: cryptography>=43
Requires-Dist: keyring>=25.7.0
Requires-Dist: livekit>=1.1.17
Requires-Dist: mnemonic>=0.21
Requires-Dist: numpy>=1.26
Requires-Dist: opencv-python-headless>=5.0.0.93
Requires-Dist: segno>=1.6.6
Requires-Dist: supabase
Requires-Dist: textual
Requires-Dist: textual-image>=0.13.2
Requires-Dist: vodozemac>=0.10.0
Description-Content-Type: text/markdown

# circle

Chat with your circle of friends, entirely in the terminal. Text, audio calls, and video.

## Install

circle is distributed on PyPI and installed with [uv](https://docs.astral.sh/uv/):

    uv tool install circle-chat
    circle

`uv tool install` puts the `circle` command on your PATH; run `circle` to start. If you don't
have uv yet:

    curl -LsSf https://astral.sh/uv/install.sh | sh

## Join

circle is invite only. A friend already in the circle makes you a code from **INVITE** (`^N`);
each member can bring in 3 people.

1. Run `circle` and type `:register`.
2. Enter the invite code, your email and a passphrase of 12 characters or more.
3. circle mails you a 6 digit code from `access@mail.gaibulloev.com`; type it in. No mail? Type
   `:resend`, and look in spam.
4. Pick an @handle (`a-z`, `0-9`, `_`, 3 to 20) and the name friends see.
5. Write down the 8 burn codes circle shows. Each one removes your second factor or resets your
   passphrase when the phone or the mailbox is lost.
6. Write down the 24 recovery words, then type back the 3 circle asks for. They bring your identity
   and history to a new computer, and nobody, circle included, can give them back.

You land in the chat, already friends with whoever invited you. Your email stays private: friends
see your @handle. circle mails it only codes and account notices, from `access@mail.gaibulloev.com`
through Resend.

## End to end

Messages and calls are encrypted on your computer for each of your friend's computers and your
own. The server stores who wrote to whom and when, never the text, and your history lives on
your computers, backed up under your 24 recovery words.

To check that nobody sits between you and a friend, open their chat, press `^Y` and compare the
60 digits with theirs, face to face or on a call. VERIFY marks the key; if it ever changes, circle
stops sending to that friend until you compare again. An unverified friend's new key shows
KEY CHANGED once, as when they start on a new computer without LINK.

## Sign in on another computer

Install circle there and sign in with your email and passphrase. The new computer then asks how
to get your keys:

- `:link` shows 3 numbers. On a computer where circle already runs, open **DEVICES** (`^D`), press
  LINK and type those numbers. Your keys and history move over.
- `:words` takes your 24 recovery words and brings back your keys and history.
- `:fresh` starts a new identity. Friends see KEY CHANGED, and your old messages stay only on your
  other computers.

Each computer keeps its own session; **SIGN OUT** (`^O`) ends it on this one or on all of them.
**SETTINGS** (`^G`) makes new recovery words.

## Forgot the passphrase

Type `:recover`, enter your email, then the 6 digit code circle mails you, then a new passphrase.

## Update

    uv tool upgrade circle-chat

A circle older than 0.3.0 can no longer send: it shows "circle 0.3.0 is out" under the
composer until it is upgraded.

If that still reports the old version (uv can cache the package index), force a clean reinstall:

    uv tool install --force --no-cache circle-chat

Check what you're running with `uv tool list`. To remove circle entirely: `uv tool uninstall circle-chat`.

## Video quality by terminal

Video adapts to whatever terminal each person runs — no setup:

| Terminal                          | How video looks                    |
|-----------------------------------|------------------------------------|
| iTerm2, kitty, WezTerm, Ghostty   | HD pixels (Sixel or Kitty graphics)|
| Terminal.app, tmux, herdr         | 2×2 colour blocks (works anywhere) |

Call quality is per person: whoever runs a graphics-capable terminal is seen in HD. Two commands
tell you what to expect before a call:

    circle termcheck    # which video mode this terminal will use, and why
    circle videocheck   # show your own camera in the video panel, no call needed

On macOS the terminal asks for camera and microphone permission the first time; if a prompt is
missed, allow your terminal under System Settings → Privacy & Security. `circle camcheck` and
`circle miccheck` verify each. `circle --help` lists every command.

## Development

    uv run pytest

runs the offline tests; with a `.env` that holds `SUPABASE_SERVICE_ROLE_KEY` it also runs the live
tests, which make and delete their own accounts on the project. The SQL checks the live project
cannot take, forced interleavings and one mutation per rule, run on a throwaway local Postgres:

    uv run --python 3.12 --no-project --with pgserver --with "psycopg[binary]" python tests/local_pg/run.py
