# Terminal frontend

`tidesi-cli` renders the same provider data as a table, with no Plasma,
Quickshell or compositor involved. It is the way to use this on a desktop the
widget cannot be installed on — Plasma 5, GNOME, XFCE — as well as over SSH, in
a shell prompt, or in a status bar.

## Getting it on PATH

```bash
# From a cloned checkout: put the tools on PATH …
export PATH="$PWD/backend/sh:$PATH"

# … or link just the frontend (it resolves symlinks to find its package)
ln -s "$PWD/backend/sh/tidesi-cli" ~/.local/bin/tidesi-cli

# … or, on NixOS, run it straight from the flake without installing anything
nix run .#cli
nix run github:Muddyblack/tidesi#cli
```

If the widget is already installed, its settings page lists the path under
**Terminal** with a copy button, so the plasmoid directory does not have to be
hunted down by hand.

## Usage

```bash
tidesi-cli                        # every enabled provider
tidesi-cli --provider claude,zai  # a subset, ignoring the toggles
tidesi-cli --compact              # one line, for status bars
watch -n 300 tidesi-cli           # refresh in place
get-ai-usage --all | tidesi-cli   # render an envelope you already fetched
```

```
PROVIDER  PLAN          WINDOW             USAGE                NOTE                      RESET
────────────────────────────────────────────────────────────────────────────────────────────────────────
Claude    max           5-hour session     [██░░░░░░░░]  23%    120000 / 500000 tokens    Jul 19, 17:00
Claude    max           7-day window       [██████░░░░]  61%    3000000 / 5000000 tokens  Jul 25, 17:00
────────────────────────────────────────────────────────────────────────────────────────────────────────
Z.AI      pro           5-hour tokens      [██░░░░░░░░]  25%    250 / 1000 tokens         Jul 25, 20:20
Z.AI      pro           Monthly tools      [████░░░░░░]  40%    60 remaining              Jul 25, 21:20
────────────────────────────────────────────────────────────────────────────────────────────────────────
Kimi      Moonshot API  Available balance  $49.59
────────────────────────────────────────────────────────────────────────────────────────────────────────
Copilot   —             —                  Copilot: no token configured
```

Colour follows the same thresholds as the panel indicators (amber from 70%, red
from 90%) and switches off automatically when the output is not a terminal, or
when `NO_COLOR` is set. `--color always|never` overrides that, and `--ascii`
replaces the box drawing for terminals without a UTF-8 locale. Columns that stay
empty — a provider set with no reset times, say — are dropped rather than
printed blank. A provider that cannot report keeps its row and shows the reason,
so a missing key does not look like a service you never enabled.

## Configuration

Without a widget there is no settings page to write the config, so create it
once by hand at `~/.config/tidesi/hyprland-settings.json` (or under
`$XDG_CONFIG_HOME`; `TIDESI_CONFIG` overrides the path). Provider defaults are
zero based. Run `get-ai-usage --initialize-provider-defaults` when you want the
one-shot local detection policy applied, or set the `providers` booleans
yourself. Credentials go in `keys`, and the `WIDGET_*` environment variables
win over the file if you would rather not store them:

```json
{
  "providers": { "claude": true, "zai": true, "kimi": true, "openai": false },
  "keys": { "zai": "…", "moonshot": "…" }
}
```

The initializer returns `{"ok":true,"data":{...settings...}}` and persists
`providerDefaultsApplied: true`. It does not run implicitly for `--all`.
Detection enables only the approved providers whose tool is installed (old
logs and credential files do not count). See
[`provider-detection.md`](provider-detection.md) for the allowlist, privacy
limits, migration behavior, and platform differences.

Claude needs no key — a local Claude Code login is enough. See
[`providers.md`](providers.md) for what each of the others reads.


Junie local usage is available with `get-ai-usage --provider junie` and
`tidesi-cli --provider junie`. It is marked untested, reads local CLI sessions,
and exposes no account quota or billed dollar spend. See
[Junie setup](providers.md#junie-cli-untested), including Google BYOK commands.