ovos-tui-client

A split-pane terminal UI for talking to and debugging OpenVoiceOS without a microphone or speaker - type what you'd say, read what OVOS says back, and watch exactly what's happening on the message bus while it happens.

Actively maintained. The core experience is stable today and it's a solid, working replacement for the old CLI clients - see the comparison below. It'll keep picking up refinements and fixes, but you don't need to wait for a "1.0" to get real use out of it.

What it looks like

The four panes in text form, for anywhere images don't render (a plain-text README viewer, pip show, etc):

┌────────────────────────────────────────────┐
│ Sources: [X]bus [X]skills [X]audio ...     │
│ Log Levels: [X]DEBUG [X]INFO ... Skills:.. │
│ Filter logs (free text)...                 │
│ LOGS                              scroll↕  │
├────────────────────────────┬───────────────┤
│ CONVERSATION (2/3)         │ ACTIVITY (1/3)│
│ You: read me a grimm story │ 🔍 pipeline:  │
│ OVOS: Here's Cinderella... │ asking all... │
│                            │ 📥 grimm-tale │
│                            │ s: "Cindere.. │
├────────────────────────────┴───────────────┤
│ > _                                        │
└────────────────────────────────────────────┘

Four panes at once: raw logs, a normal back-and-forth conversation, a live simplified feed of what's happening behind the scenes, and a text input that stands in for your voice. Everything updates in real time as OVOS processes what you type.

What it does

• Logs - tails every OVOS service log it can find (bus, skills, audio, voice, GUI, PHAL, etc), color-coded by source, timestamps stripped for readability, errors bolded. Filter by source, log level, free text, or a specific skill - any combination, live, without restarting anything (with nothing checked in a category everything shows; checking one or more narrows to just those). Scroll up to read something and new lines won't yank you back down.
• Conversation - what you typed and what OVOS said back, plus quiet status lines for everything else this tool does (service restarts, skill toggles, startup info) kept visually distinct so they don't clutter the actual conversation.
• Activity - a simplified, human-readable feed of what's happening on the bus right now: which skill is handling the request, wake word and speech start/stop, which fallback skill caught something nothing else understood (and whether it actually resolved anything), and for content-reading requests specifically, which providers answered and at what confidence.
• A searchable command palette (Ctrl+P) for everything else - restart a stuck service, activate or deactivate a skill, check the intent pipeline order, or toggle any log filter - all searchable by typing, with results appearing right in the conversation pane instead of popup windows. A help panel (F1) covers the rest of the keybindings.
• Type what you'd say and press Enter, same as talking to a real OVOS device. Up/Down arrows browse what you've typed before, like shell history.

Why this is worth having

Testing OVOS by voice means dealing with wake-word misfires, STT mistakes, and no visibility into why something did or didn't happen. Typing directly and watching the activity feed skips all of that - and makes some genuinely hard-to-see things visible:

• See which skill actually answered - and which ones tried and gave up. Ask a factual question and watch each candidate skill respond in real time, including the ones that came back empty - useful for figuring out why you got a weird or unhelpful answer instead of a good one.
• Catch vocabulary gaps as you find them. Type a phrasing you'd expect to work; if nothing responds, or the wrong skill claims it, that's immediately visible instead of a silent failure you'd only notice by accident.
• Understand fallback behavior. When nothing matches normally, OVOS asks a chain of fallback skills whether they can help - the activity feed shows exactly which one stepped in, and whether it actually resolved anything or just apologized.
• Check the intent pipeline order without digging through config files. Search "pipeline" in the command palette to see every matching stage in the exact order OVOS evaluates them.
• Restart a stuck service in two keystrokes, without switching to another terminal.

None of this requires working audio hardware, a wake word, or STT accuracy getting in the way - just type.

Install

pip install ovos-tui-client

A container image is also published on every release - see Docker/Podman companion image below if that fits your setup better.

Usage

ovos-tui

Connects to 127.0.0.1:8181 by default. Options:

ovos-tui --host 192.168.1.50 --port 8181 --lang da-dk --log-dir ~/.local/state/mycroft --mycroft-conf ~/ovos/config/mycroft.conf

• --log-dir: the log directory is auto-detected against a list of known candidate paths (which vary by OVOS install method). If nothing is found, the logs pane says so - pass this to point at the right directory explicitly.
• --mycroft-conf: path to a specific mycroft.conf for the pipeline view in the command palette to read. Only needed on Docker/Podman installs (see below) - without it, the pipeline view may read the wrong file or find nothing on those installs. It won't crash, but it won't be accurate either.

Running as a web app instead of in a terminal

pip install ovos-tui-client[web]
ovos-tui --web

Visit the printed URL in a browser and use the exact same interface - no separate app, just this one running on a server instead of your own terminal. --web-port sets the port (default 8000); --web-host sets which address it's reachable at (auto-detected if you don't set it, since guessing wrong here shows a broken, unstyled page instead of a clear error).

Docker/Podman installs

This tool runs on the host, not inside the same containers OVOS runs in, so a couple of things need extra attention on a Docker/Podman install - the notes below are based on reading ovos-docker's own documentation directly, not guessed at:

• Logs work even with no log files on the host. ovos-docker's own sample mycroft.conf sets "logs": {"path": "stdout"} - on an install that follows that guide as written, there are no log files on the host filesystem at all, only container stdout. When this tool finds no log files but detects a Docker/Podman install, it automatically bridges each container's docker logs -f (or podman logs -f) into the same small set of log files a normal install already produces - skills.log, audio.log, voice.log, etc, grouped by container name pattern (every ovos_skill_* container lands in skills.log together, ovos_audio in audio.log, and so on; anything unrecognized goes to other.log) - not one file/ checkbox per container. Confirmed against a real ovos-docker install with 26 running containers: this keeps the Sources: checkboxes down to a handful of familiar categories with the usual colors, instead of two dozen individually-named ones. Bridge processes are cleaned up on quit. If bridging isn't possible for some reason (no docker/podman binary available), it says so explicitly instead and points at docker logs <container> / docker compose logs -f directly.
• Services run as containers, not background services this tool can query the usual way - it detects this and says so explicitly (with a count, not a list of every container name - docker ps/ podman ps already exists for that), rather than just showing an unexplained empty result. Restarting a container from here isn't supported yet.
• Skills - Skill: activate/deactivate can be very limited on a distributed, one-container-per-skill install: skillmanager.list (the bus message this relies on) only reports skills loaded in the same process as whichever component answers it, which on this kind of install is basically nothing - confirmed directly against a real install. Not a bug in this tool specifically; there isn't currently a bus message with full visibility across a distributed skill deployment (tracked in issue #26).
• Pipeline - see --mycroft-conf above; also confirmed against ovos-docker's real .env variables (OVOS_CONFIG_FOLDER, default /home/ovos/ovos/config), not assumed.
• One real quirk worth knowing about: on some installs ovos-messagebus runs as a native binary that logs via stdout/the systemd journal rather than a file - if a bus source never shows up even though everything else does, that's likely why, not a bug here.

Docker/Podman companion image

Unlike every other OVOS container (audio, listener, messagebus, each skill), this one isn't a background service - it's an interactive terminal tool, so it needs a TTY attached to actually draw anything:

docker run -it --rm --network host ghcr.io/andlo/ovos-tui-client:latest

--network host is the simplest way to reach a messagebus already listening on the host's 127.0.0.1:8181; on an ovos-docker install specifically, joining that stack's own compose network and pointing --host at the messagebus container's name instead works too, and is usually the better fit if this is meant to run alongside it long-term. Pass this tool's own flags after the image name, same as the pip install - e.g. docker run -it --rm --network host ghcr.io/andlo/ovos-tui-client:latest --lang da-dk. --web works here too (see above) - --network host is the reliable choice for it, so the auto-detected address is the host's real one, not an internal container-only address a browser outside can't reach.

If the same volumes ovos_core uses for config/logs are mounted into this container too (-v/compose volumes:, matching whatever paths that install already uses), this tool sees the real files directly at their normal locations - no --mycroft-conf override or log-bridging needed at all in that case, the same as a native install would.

Log bridging and Services: detection need the Docker/Podman socket mounted in too, since this tool shells out to docker ps/docker logs -f - the image includes the docker CLI, but without the socket (-v /var/run/docker.sock:/var/run/docker.sock) there's nothing for it to talk to, and this tool quietly finds nothing rather than erroring (confirmed via live testing: logs/services just show empty, same as if there were genuinely no containers). Mounting the socket is a real, deliberate security tradeoff - it hands this container effective control over the host's whole Docker daemon - so it's opt-in, not a default.

If mounted, the container's own non-root user won't have permission to use the socket as-is. --user root on docker run fixes this on a standard dockerd install (confirmed working) - matching the group GID owning the socket instead is the more targeted alternative if running as root isn't appealing:

docker run -it --rm --network host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --user root \
  ghcr.io/andlo/ovos-tui-client:latest

Confirmed NOT sufficient on its own under rootless Podman specifically (even --user root didn't help there in testing) - if you're on Podman rather than a standard root-owned dockerd socket, this may need more digging into your specific setup.

Images are tagged by version (:0.1.20) and :latest, built and published automatically on every release.

Why not just fix ovos-cli-client / neon-cli-client?

ovos-cli-client (last released March 2022) installs cleanly via pip, but crashes immediately on launch on a fresh install: ModuleNotFoundError: No module named 'ovos_utils.configuration' - its ovos_utils dependency is unpinned, and the module it imports from has since been removed/relocated in current ovos_utils releases. It was never updated to match. Confirmed directly (pip install ovos-cli-client && ovos-cli-client) rather than assumed.

neon-cli-client pulls in neon-utils, which pins pyyaml~=5.4 - a version with no prebuilt wheel for modern Python and a build script incompatible with current setuptools (workaround: pin setuptools<58 first).

Building this tool instead avoids both dependency chains, and adds genuinely useful features - toggleable/filterable logs, service restart, a simplified activity feed - neither of the above has.

No existing project fills this specific niche as of writing (checked the OpenVoiceOS GitHub org's repositories and general TUI project listings) - if that's changed by the time you're reading this, please open an issue and point at it.

Category

Development Tools

Tags

#ovos #tui #testing #cli #development