Metadata-Version: 2.4
Name: ovos-tui-client
Version: 0.1.15
Summary: A split-pane terminal UI for testing OVOS without a mic/speaker
Home-page: https://github.com/andlo/ovos-tui-client
Author: Andreas Lorensen
Author-email: andlo@outlook.dk
License: GPL-3.0-or-later
Project-URL: Source, https://github.com/andlo/ovos-tui-client
Project-URL: Bug Tracker, https://github.com/andlo/ovos-tui-client/issues
Keywords: ovos textual tui cli-client messagebus voice-assistant testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.60
Requires-Dist: ovos-bus-client
Requires-Dist: ovos-config
Requires-Dist: ovos-utils>=0.8.0
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ovos-tui-client

A split-pane terminal UI for talking to and debugging [OpenVoiceOS](https://www.openvoiceos.org/) 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](#why-not-just-fix-ovos-cli-client--neon-cli-client) 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.

[![Tests](https://github.com/andlo/ovos-tui-client/actions/workflows/test.yml/badge.svg)](https://github.com/andlo/ovos-tui-client/actions/workflows/test.yml)
[![PyPI version](https://img.shields.io/pypi/v/ovos-tui-client.svg)](https://pypi.org/project/ovos-tui-client/)
[![ovos-cli-client](https://img.shields.io/pypi/v/ovos-cli-client.svg?label=ovos-cli-client)](https://pypi.org/project/ovos-cli-client/)

## What it looks like

![ovos-tui-client screenshot](https://raw.githubusercontent.com/andlo/ovos-tui-client/main/ovos-tui-client.png)

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

```bash
pip install ovos-tui-client
```

## Usage

```bash
ovos-tui
```

Connects to `127.0.0.1:8181` by default. Options:

```bash
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
