hikariming/openkoto/openkoto

Purpose

OpenKoto is a language-learning app (iOS / desktop / web) that syncs the user's vocabulary cards, word packs, articles, song lyrics and books through the cloud. The koto CLI reads and writes that cloud library directly, so every change shows up on all of the user's devices right away.

Always drive the CLI with --json and parse stdout. Never scrape the human-readable output.

Hard Rules

• Pass --json on every command. On success stdout is one JSON document. On failure stdout is {"error":{"code","message","exitCode"}} and the process exits non-zero.
• Check the exit code first:
• 0 ok
• 2 usage error: fix the arguments
• 3 not logged in: ask the user to run koto login; don't try to log in for them
• 4 plan or quota: tell the user; free accounts get 50 CLI/MCP calls a day (FREE_LIMIT_REACHED, resets 00:00 UTC; Plus is unlimited) and have storage limits. Don't retry
• 1 anything else: report the message
• Changes are real and sync to all devices. Before a bulk write (import, more than ~10 adds, overwriting translations), confirm with the user. There is no bulk-delete command; koto vocab rm <id> deletes one card. Only use it when the user asks.
• Ids are opaque strings. Always take them from previous --json output, never invent them.
• Never print or log byok.api_key or KOTO_API_KEY.
• Don't run koto vocab review. It is an interactive TTY session for humans. To review with the user, use vocab due and vocab grade (see workflows/daily-review.md).

Setup check

koto whoami --json      # exit 3 → not logged in; entitlements.cliDailyLimit: 50 on free, null on Plus/Pro

If koto is missing: npm i -g @openkoto/cli, then the user runs koto login. The login prints a code and opens the browser. For CI or headless use, set KOTO_API_KEY=ok_live_…, created at openkoto.com → Settings → API keys.

Command reference

A Vocab object has these fields: id, word, meaning, reading?, example?, usage?, srsState ("new"|"learning"|"review"), dueDate (YYYY-MM-DD), reviewCount, stability, difficulty, lastReviewedAt?, suspendedAt?, packIds[].

Lyrics translation engines

• --byok translates locally with the user's own OpenAI-compatible provider (koto config set byok.base_url|byok.api_key|byok.model). It costs no OpenKoto credits and works without calling the API unless --save is given.
• Without --byok the CLI uses hosted AI, which needs Pro or AI credits. When that is unavailable it exits 4 (or 1 with HOSTED_AI_NOT_AVAILABLE_YET). Suggest --byok.
• If aligned is false, some translation values are empty. Fill them in yourself, then write them back with koto lyrics translate … --save, or use the MCP tool save_lyrics_translation.
• You can also translate the lines yourself: read the lines with koto lyrics show <id> --json, then save them with the MCP tool save_lyrics_translation.

Workflows

• workflows/lyrics-study.md: translate a song, then pick vocabulary into a word pack
• workflows/novel-reading.md: browse a book, read or summarise chapters, save words
• workflows/daily-review.md: run today's review conversationally and report progress

MCP alternative

If the openkoto MCP server is configured, prefer its tools. It is either the remote server https://openkoto.com/mcp or the local npx @openkoto/mcp (see README.md).

• Read: search_library, list_due_vocab, get_review_stats, get_lyrics, list_books, read_chapter
• Write: add_vocab, update_vocab, review_vocab, save_lyrics_translation, create_lyrics
• Hosted AI (spends credits): translate_lyrics, create_word_pack_from_text

They return the same JSON shapes as the CLI.