Skip to main content

CLI tools

kgrep, ksed, kcat and kdiff are format-aware reimaginings of the classic Unix text utilities. grep, sed, cat and diff operate on raw bytes: the lines of a file as the operating system stores them. These four read, rewrite and compare the text content inside any format kapi understands, regardless of how that text is encoded on disk. It is the same content engine the rest of kapi runs on, exposed as the Unix verbs you already know.

The practical consequence: you can search the prose inside a Word .docx, rewrite a phrase across a directory of JSON catalogs, or print the segments of an XLIFF file as plain text, using muscle memory from tools you already know, without first converting anything.

kdiff extends the same idea to diff: it compares the text of two files block by block, so a reflowed .docx or a reordered JSON catalog shows only the prose that actually changed. Given a single file and a target locale, it reports which blocks are still untranslated.

A fifth utility, kconv, has no classic Unix analog: it converts between formats (a .docx to clean Markdown, a DocLang document to HTML, or any supported format to DocLang), carrying the document's structure across rather than its bytes.

The video below shows the whole loop on a sales team's collateral: a Markdown pitch, a Word proposal, and an Excel price list. kcat prints the text inside each file, kgrep finds the product name across all three at once, and a single ksed rebrands it everywhere, rewriting each document back into its own format.

Each works on every one of the 40+ file formats neokapi reads: Office documents, message catalogs and data formats, markup, and more. See the Format Reference for the full list.

Why blocks, not lines​

A .docx has no "lines" in the byte sense; a JSON catalog's meaningful units are keyed strings, not file rows. kapi parses a document into blocks of content and strips the surrounding markup and structure. The toolbox operates on those blocks:

  • kcat prints one block per output line.
  • kgrep reports one matching block per line, and -n prefixes the block's ordinal position. For genuinely line-oriented formats such as plain text, one block is one line, so -n reads exactly like grep -n.
  • ksed rewrites a block's text and asks the format writer to reconstruct the document, so structure is preserved.
  • kdiff aligns the blocks of two files (by key for catalogs, by content for prose) and reports added, removed, changed and moved blocks rather than changed bytes.
  • kconv hands the blocks, and the role each one carries (heading, list item, table cell), to a different format's writer, projecting the document's structure into the target format.

Installation​

The Kapi CLI bundles these commands:

brew install neokapi/tap/kapi-cli  # macOS/Linux

See Installation for the release channels.

On Windows, winget install Neokapi.KapiCli installs kapi 1.0.2, which predates the behaviour this page describes. Take a Windows build from the direct downloads instead.

Every utility is also reachable as a kapi subcommand under the same name: kapi kgrep, kapi ksed, kapi kcat, kapi kdiff, kapi kconv. Each behaves identically to the standalone short name on every platform. (The proxies carry the k-names so every bare verb stays free: bare kapi diff is the connected-project sync diff, not a file diff.)

Windows

The Homebrew install adds the short names (kgrep, ksed, kcat, kdiff, kconv) as aliases of the kapi binary. The Windows zip carries the single kapi command, so on Windows use the subcommand form (kapi kgrep, kapi ksed, kapi kcat, kapi kdiff, kapi kconv), which is exactly equivalent.

Conventions shared across the toolbox​

  • Standard input. With no file argument, or when the file is -, input is read from standard input. Without a file extension to go by, the format is sniffed from the content and falls back to plain text.
  • Format selection. -f, --format overrides format detection (for example -f json). Note this differs from grep/sed, where -f reads patterns or scripts from a file; in the toolbox -f always means format, matching the rest of the kapi CLI. Use -e for explicit patterns and scripts.
  • Source vs. translation. For multilingual formats the utilities by default operate on the source text. --target LOCALE operates on a target language instead. For example, kgrep --target fr "déconnexion" messages.xliff searches the French translations.
  • Files and directories. Glob patterns expand in-process, so a quoted 'src/**/*.md' behaves the same in every shell. A directory argument needs -r, --recursive; without it, it is reported and skipped, as in grep. The one exception is ksed, which spells it -R: sed's own -r means --regexp-extended, so the letter is left alone.
  • Binary input is refused. A file that no format claims and whose bytes are binary (a .dmg, an installer, an image with no reader) is reported and skipped rather than read as plain text, so a glob over a downloads folder cannot spray raw bytes at the terminal or into a converted file. Other files in the same run are unaffected, and the exit status is 2. -f FORMAT overrides the guard when you mean it.