The Textual TUI requires a terminal that supports ANSI escape
codes. Windows Terminal (from the Microsoft
Store) provides the best experience. The legacy
cmd.exe and older PowerShell ISE may render
incorrectly.
WINDOWS TERMINAL — INSTALL
PS> winget install
Microsoft.WindowsTerminal
Common Issues
Close and reopen PowerShell. uv's installer adds to your
PATH via the user profile. If still not found, check
$env:USERPROFILE\.local\bin is in
$env:PATH.
Run uv run playwright install chromium again.
If it fails, check that you have sufficient disk space
(~300MB) and that Windows Defender isn't blocking the
download.
Use Windows Terminal instead of cmd.exe or the default
PowerShell window. Set your terminal font to a Nerd Font
like Cascadia Code NF for proper block
character rendering.
Upgrade
UPGRADE — WINDOWS
PS> git pull origin main
PS> uv sync
macOS Setup
Prerequisites
🍎
macOS 12+
Monterey or later recommended. The Textual TUI renders
correctly in macOS Terminal.app and iTerm2.
🍺
Homebrew
Optional but recommended for managing Python and git.
Install from brew.sh.
MACOS TERMINAL
# Install uv$ curl -LsSf
https://astral.sh/uv/install.sh | sh
$ source ~/.zshrc
# or ~/.bashrc# Optional: install Python via Homebrew$ brew install python@3.13 git
# Clone & setup$ git clone
https://github.com/grep-many/thread-vault-cli.git
$ cd thread-vault-cli
$ uv sync
$ uv run playwright install
--with-deps chromium
# Launch$ uv run python -m app
macOS-Specific Notes
ℹ
macOS may show a security prompt when Playwright first
launches Chromium ("This app is downloaded from the
internet"). Click Open to allow it. This is a
standard macOS Gatekeeper dialog for downloaded executables.
Common Issues
Run
/Applications/Python\ 3.13/Install\
Certificates.command
if you installed Python from python.org. Homebrew Python
should handle this automatically.
Go to System Preferences → Security & Privacy → General,
and click "Open Anyway". Or run:
xattr -d com.apple.quarantine $(uv run playwright
show-browser chromium)
Add export PATH="$HOME/.local/bin:$PATH" to
your ~/.zshrc and run
source ~/.zshrc.
Upgrade
UPGRADE — MACOS
$ git pull origin main && uv
sync
Linux Setup
Supported Distributions
🐧
Ubuntu 20.04+
🌀
Debian 11+
🎩
Fedora 36+
🏹
Arch Linux
🦎
openSUSE
📦
Other systemd
UBUNTU / DEBIAN
# Install system dependencies$ sudo apt update
$ sudo apt install -y
python3.13 python3.13-venv git curl
# Install uv$ curl -LsSf
https://astral.sh/uv/install.sh | sh
$ source ~/.bashrc
# Clone & setup$ git clone
https://github.com/grep-many/thread-vault-cli.git
$ cd thread-vault-cli
$ uv sync
# Install Playwright system deps (required on Linux)$ uv run playwright install
--with-deps chromium
# Launch$ uv run python -m app
FEDORA / RHEL
$ sudo dnf install -y
python3.13 git curl $ curl
-LsSf https://astral.sh/uv/install.sh | sh
$ source ~/.bashrc
$ git clone
https://github.com/grep-many/thread-vault-cli.git
$ cd thread-vault-cli && uv
sync $ uv run playwright
install --with-deps chromium
$ uv run python -m app
ARCH LINUX
$ sudo pacman -S python git
curl $ curl -LsSf
https://astral.sh/uv/install.sh | sh
$ source ~/.bashrc
$ git clone
https://github.com/grep-many/thread-vault-cli.git
$ cd thread-vault-cli && uv
sync $ uv run playwright
install --with-deps chromium
$ uv run python -m app
Linux-Specific Notes
ℹ
On Linux,
playwright install --with-deps chromium installs
system-level library dependencies (libnss, libgconf, etc.) via
apt or dnf. You may need
sudo for the system deps installation. On
headless servers (no display), Browser Login requires setting
DISPLAY or using a virtual framebuffer
(xvfb-run).
Headless Server Setup
XVFB VIRTUAL DISPLAY (SERVER)
$ sudo apt install -y xvfb
# Launch with virtual display (for Browser Login on
headless machines)$ xvfb-run uv run python -m
app
# Alternatively, use Session ID auth (no display
required)
Common Issues
Add the deadsnakes PPA (Ubuntu):
sudo add-apt-repository ppa:deadsnakes/ppa &&
sudo apt install python3.13. Or use pyenv: pyenv install 3.13.
Re-run
uv run playwright install --with-deps chromium
— the --with-deps flag installs required system
libraries. If this fails, check your distro's equivalent of
apt install libnss3 libgconf-2-4.
Thread Vault uses WAL mode but SQLite still serializes
writers. Ensure no other instance of Thread Vault is
running. Check with fuser data/vault.db.