kotoba --once — one question, one answer

kotoba --once "explain what a WAL journal is"
kotoba --once "read notes.md and tell me what changed"

One turn, her answer on stdout, exit. It is the form for a script, a cron entry, a shell alias, a keybinding — anywhere a full-screen session would be in the way.

$ kotoba --once "hola"
¡Hola! Qué gusto verte por aquí. ¿Cómo te llamas?
$ echo $?
0

It is the same Kotoba

Not a stripped-down mode. Same database, same memory, same tools, same working folder, same approvals. The turn is persisted, so what you ask here she remembers in the browser, and what you told her in the browser she knows here.

She writes for a screen: fenced code with a language, real file paths, real URLs, digits. Over voice all of those are banned, because "backtick backtick backtick python" is not something anyone wants to hear. Nothing configures this — the register follows the surface, so there are never two settings to keep in step.

It runs on the barest install

--once never imports rich or prompt_toolkit, so pip install kotoba-companion with no extras at all still answers. It is also the command that works on every platform, including Windows.

With no key configured and a terminal on stdin, it opens the setup wizard first rather than handing you her "I have no key" line with no way to fix it. Piped, there is nothing to ask with, so it does not try.

Answering an approval

There is no card here — nothing in this path draws one. A command she wants to run arrives as a line prompt on stderr, so it never lands glued to her answer on stdout, and it takes Enter:

npm install left-pad
allow? [y/N/a/t] — a = always allow npm — t = always allow just this line

Piping an answer in works. With stdin closed there is nobody to ask, so the card is refused rather than left waiting.

Exit codes

The distinction on 1 is the point: ask returns text whether the turn worked or not, so a script reading only stdout would file an apology as the result. The status line carries what the text cannot.

$ SOUL_PATH=/nope/missing.md kotoba --once "hola"
She could not start: SOUL file not found. SOUL_PATH='/nope/missing.md'; tried: /nope/missing.md
`kotoba doctor` checks everything she needs and says what is missing.
$ echo $?
1

Nothing that fails prints a stack trace. The full traceback goes to ~/.kotoba/cli.log; the terminal gets what happened and the one command that says how to fix it.

Ctrl+C

Ctrl+C cancels the turn, not the process. Whatever she had already said is printed first, then — interrupted — on stderr, then it exits 130. Her words are persisted either way, so a partial that was never shown to the person who asked for it would be a real loss.

On a platform where the event loop cannot install a signal handler for SIGINT — which the code guards for by name, and which includes the Windows proactor loop — that handler is simply not installed. The interrupt still ends the command with 130. What reaches the screen on that path is not something this page has measured; see Platform support.

The rendering flags apply to her words too

kotoba --ascii --once "¿qué tal?"

--ascii on this command folds her prose, not only the chrome — this is the command that prints it. The fold is still a fixed table of glyphs, so the accents survive and only the em dashes, ·, → and box rules are replaced. A flag for a terminal that cannot draw a glyph is not a flag for a product that speaks your language.

--plain, --calm and --no-face are accepted here too. They change nothing about her answer — --once prints text, and has no colour, motion or portrait to give up — but they do apply to the setup wizard on the run where --once opens it.