EchoVault CLI

A terminal (TUI) music player for your EchoVault library, built with Textual and pygame.

Requirements

EchoVault CLI doesn't manage its own music library — it reads the same local database that the main EchoVault desktop app builds when you add folders to your library. Install and run EchoVault at least once first, so ~/.config/EchoVault/sonicbox.db exists and has tracks in it.

Installation

pip install EchoVault-CLI

Requires Python >= 3.8.

Usage

Run the player from a terminal:

echovault

Select a track in the list and use these keys to control playback:

CLI Preview

Development

1. Clone and install in editable mode (picks up code changes immediately, no reinstall needed per edit):

   git clone https://github.com/EchoVaultHQ/EchoVault-CLI.git
   cd EchoVault-CLI
   pip install --user -e .
   

2. Run it:

   echovault
   

   or directly via module: python -m echovault.app

3. Live-reload dev mode — Textual can watch app.tcss and hot-reload styles without restarting, plus stream logs to a separate console. This needs the textual-dev package (not a runtime dependency, install it separately):

   pip install --user textual-dev
   

   Then, in two terminals:

   # terminal 1 — devtools console (shows logs/errors)
   textual console
   
   # terminal 2 — run the app in dev mode
   textual run --dev echovault.app:EchoVault
   

   Note: pass the module path as module:AppClass (echovault.app:EchoVault), not a file path — textual run --dev src/echovault/app.py runs the file standalone and breaks its relative imports (from .database import ...).

   Edit src/echovault/app.tcss while the app is running and the styling updates live.

4. Run the test suite:

   pip install --user pytest
   pytest tests/
   

Deployment

Releases publish to PyPI automatically via GitHub Actions (.github/workflows/publish.yml) whenever a v* tag is pushed.

1. Bump the version in src/echovault/__about__.py:

   __version__ = "X.Y.Z"
   

2. Commit the bump:

   git add src/echovault/__about__.py
   git commit -m "Bump version to X.Y.Z"
   git push origin main
   

3. Tag and push the tag to trigger the release:

   git tag vX.Y.Z
   git push origin vX.Y.Z
   

4. Watch the run under the repo's Actions tab. On success, the new version appears on PyPI.

Notes:

• Publishing uses PyPI Trusted Publishing (OIDC) — no API token is stored in the repo. The trusted publisher on PyPI must point at the current GitHub owner/repo/workflow (Settings → Actions → Publishing on the PyPI project page); update it there if the repo is ever renamed or transferred.
• Re-running a release requires a new tag or a re-pushed tag (delete + recreate) — pushing an unchanged existing tag will not retrigger the workflow.

Related Projects

• EchoVault — the main desktop music player this CLI complements.

License

EchoVault-CLI is distributed under the terms of the MIT license.