Docs
Install Dotiphant
On macOS or Linux, paste curl -fsSL https://dotiphant.com/install.sh | sh into a terminal. It installs the latest Dotiphant release and opens the setup in your browser, which takes about five minutes. Windows support is experimental.
Quick start
curl -fsSL https://dotiphant.com/install.sh | shThe script is about 150 lines; read it first. It installs uv if needed (uv brings its own Python), installs the latest Dotiphant release from GitHub with uv, and runs dotiphant open. Before installing, it checks the download against the release's SHA-256 checksums and stops on a mismatch. To update, run the same command again.
You can also check signed build provenance with gh attestation verify; see Verify a download.
Other ways to install
Dotiphant ships as GitHub releases, not on PyPI. If you already have uv:
| Goal | Command |
|---|---|
| Install a release | uv tool install <URL of the .whl file on the release page>, then dotiphant open |
| From a local clone | uv tool install . |
To install by hand and check the file yourself: download the .whl file and SHA256SUMS from the release page into one folder, check it, then install the file:
shasum -a 256 -c --ignore-missing SHA256SUMS # Linux: sha256sumuv tool install ./dotiphant-X.Y.Z-py3-none-any.whlThe command is dotiphant; phant is a short alias. If the command is not found after installing, run uv tool update-shell and open a new shell.
Setup
dotiphant open walks you through setup in your browser. It takes about 5 minutes. Prefer the terminal? dotiphant setup asks the same questions there. Both are safe to run again.
- Create your own Telegram API id and hash at my.telegram.org (free, about a minute). Telegram requires every app to have one. Click "API development tools", fill in the form (app title and short name can be anything, platform Desktop) and copy "App api_id" and "App api_hash" into the setup page.
- Log in by scanning a QR code with the Telegram app (Settings > Devices > Link Desktop Device). Phone login works too. If your account has a two-step verification password, the page asks for it.
- Choose what to archive: people and groups by default, the last 365 days or everything.
- Run the first sync. It takes from a minute to an hour for large accounts, and you can continue while it runs.
- Connect the AI apps it finds on your computer, and turn on background refresh.
Afterwards:
dotiphant open # browse and search in your browserdotiphant connect claude-desktop # or claude-code, codex, cursorFully quit and restart the AI app after connecting it. Run dotiphant status to check the login, archive size and last sync, and dotiphant doctor if anything looks wrong.
Try it without Telegram
dotiphant demoThis opens the viewer on a made-up archive, stored separately from your real data. No login needed. It uses port 8764, so it can run next to dotiphant open.
Install with an AI assistant
Not comfortable with a terminal? An AI assistant that can run commands on your computer (Claude Code, Codex, Cursor, or Claude Desktop with a terminal tool) can install Dotiphant with you. Copy this prompt into it:
Please install Dotiphant for me, following the instructions at
https://github.com/Zierold-Ventures/dotiphant/blob/main/docs/install-with-ai.md
Explain each step in plain words before you run it, and tell me exactly
what to do whenever you need something from me.You will need your phone with Telegram on it. You type your API id, hash and any codes into the setup page in your browser yourself, never into the AI chat.
Commands
| Command | What it does |
|---|---|
dotiphant open | Open the viewer at http://127.0.0.1:8765, with setup on first run. dotiphant serve does the same |
dotiphant setup | The same guided setup in the terminal. Safe to re-run; finished steps are skipped |
dotiphant sync [CHAT ...] | Fetch new messages now, for all chats or the ones named |
dotiphant status | Login, archive size, last sync, background refresh |
dotiphant doctor | Check the installation and print fixes |
dotiphant connect [APP] | Connect an AI app to your archive, or list the apps it can connect |
dotiphant chats | List archived chats |
dotiphant search QUERY | Full-text search, with --chat, --since, --json |
dotiphant export CHAT | Print a chat as Markdown, --since 7d, --out FILE |
dotiphant recent | What happened in the last 24 hours |
dotiphant media CHAT | Download photos, files and voice notes of a chat |
dotiphant schedule install | Refresh in the background every N minutes |
dotiphant mcp | The MCP server (AI apps start this themselves) |
dotiphant mcp --http --public-url URL | Remote access for ChatGPT, claude.ai and other remote MCP apps |
dotiphant import PATH | Add a Telegram Desktop JSON export (result.json), or a chat from WhatsApp's own "Export chat" (.zip or .txt), to the archive. Experimental. Nothing connects to WhatsApp |
dotiphant forget CHAT | Delete a chat and its media from the archive, and stop syncing it |
dotiphant demo | Try the viewer with made-up chats |
dotiphant login / dotiphant logout | Log in again, or end the session |
CHAT can be a chat id, an @username or part of the title. Run dotiphant COMMAND --help for all options. Remote access is explained in Remote access.
dotiphant export "Acme" --since 7d | claude -p "What are the open action items?"Update and uninstall
To update, run the install command again. To remove Dotiphant and everything it stored, follow Wiping everything: stop the background refresh, log out with --forget-credentials, delete the data folder, and run uv tool uninstall dotiphant.
Install Dotiphant
Free and open source (MIT). macOS and Linux; Windows experimental. The command installs the latest GitHub release and opens the setup in your browser. It takes about five minutes.
The script is about 150 lines. Read it first, or see other ways to install. The installer verifies the download against the release checksums (SHA256SUMS) before installing. You can check signed build provenance with gh attestation verify; see Verify a download.
curl -fsSL https://dotiphant.com/install.sh | shdotiphant open # setup opens in your browser