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

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.

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.

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