The terminal

Kotoba has a terminal. It is not a thin client for the web app: it runs the same engine in the same process, against the same database, the same memory and the same working folder. Ask her something here and she knows it in the browser tomorrow.

Install it

The interactive terminal needs the cli extra. The base install does not have it.

pip install "kotoba-companion[cli]"
kotoba doctor
kotoba setup

cli brings prompt_toolkit, rich and pillow. Without it, kotoba on its own prints the install line and exits; kotoba --once, setup and doctor keep working.

The interactive terminal runs on Linux and macOS only. On Windows setup, doctor and --once work from the same install, serve and discord work from their own extras, and bare kotoba starts the web UI instead of refusing. See Platform support.

Start it

kotoba

With no key configured she opens the setup wizard first, on this same screen, and hands over to the session when it is done. You never have to run kotoba setup separately.

Two launch flags open on a panel instead of on her greeting:

kotoba --sessions     # your past conversations; enter reads one back
kotoba --settings     # the configuration, a section at a time

Both together is one screen, so the conversations win.

Four flags that change how she is drawn

--ascii folds a fixed table of chrome glyphs — em dashes, ·, →, the box rules — and nothing beyond it, so kotoba --ascii --once "¿qué tal?" still comes back with its accents.

These four are the session's own. A subcommand that cannot act on one refuses it by name rather than swallowing it, whichever side of the subcommand you type it on:

$ kotoba --calm doctor
kotoba: --calm does nothing on `kotoba doctor`. Nothing on that report moves, and it has no face to leave out.
$ echo $?
2

kotoba setup honours all four. doctor honours --plain and --ascii. serve and discord honour none.

What is on the screen

Top to bottom, the window has four things on it:

1. The header. Printed once at launch and never repainted. Her nameplate, a ● LIVE chip, her face, and a grid of facts about the process that is about to answer you. One page down: Reading the header.
2. The transcript. Everything since — your lines, her replies, tool rows, receipts. Ordinary scrollback: no alternate screen and no scroll region, so your terminal's own scrollback keeps working. Launching scrolls whatever was on screen up into it rather than erasing it.
3. The band. Above the input box, and only when there is something to say: the long job on one row, an open plan on the next. No job and no plan is zero rows.
4. The box and the bar. The input frame, and under it one status line — a chip, her face, a phrase and a right-hand slot. What the footer is telling you.

Leaving

ctrl-d leaves. So does /quit, and /exit, which is the same command under another name.

ctrl-c never leaves in one press. With something in the box it clears the box. On an empty box the first press arms and says so in the bar; the second one leaves.

A long job dies with the session. There is no daemon behind this prompt, so leaving with one running stops it and prints its row rather than letting twenty minutes of it vanish off the bottom of a scroll — with it goes when the session does as its summary. A card still waiting for you is declined on the way out, never dropped, so nothing runs behind you. The last line is her goodbye:

 ○ OFFLINE  ( －ω－ )z  see you — the transcript stays right here

Where things live

KOTOBA_HOME moves all three at once; KOTOBA_CLI_HISTORY, KOTOBA_CLI_LOG and KOTOBA_FILES_DIR move them one at a time. A home that will not take a write is never fatal — history falls back to memory, and she says so rather than ending the session.

Nothing she did not say reaches your terminal from the moment a command takes over: logging is redirected to that file before anything else runs.