Commands¶

Every command, generated from the click definitions kennis actually runs. Nothing on this page is transcribed, so an option shown here is an option the installed version accepts.

A printed command runs as printed

kennis attaches the command that resolves an error to the error itself, and that command is meant to be copied and run without editing. The same rule applies to this page.

kennis¶

A knowledge and memory system for people and AI agents.

Usage:

kennis [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-V`, `--version`	boolean	Show the version and exit.	`Sentinel.UNSET`
`-q`, `--quiet`	boolean	Print nothing but failures.	`Sentinel.UNSET`
`--no-progress`	boolean	Suppress live progress bars, not the report.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis backup¶

Write, check and restore an encrypted backup of the corpus.

Usage:

kennis backup [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis backup check¶

Whether the folder is usable, and when the backup was last written.

Usage:

kennis backup check [OPTIONS]

Options:

Name	Type	Description	Default
`--to`	path	This folder instead of backup.folder, for this run only.	`Sentinel.UNSET`
`--test`	boolean	Ask for the password and test every file in the backup.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis backup create¶

Write the corpus and its history to one encrypted .7z file.

Everything but the working copy of the index, which the history holds and a restore checks out again. The file is tested with the password before it replaces the last backup, so a failed run never destroys a good one.

Usage:

kennis backup create [OPTIONS]

Options:

Name	Type	Description	Default
`--to`	path	This folder instead of backup.folder, for this run only.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis backup restore¶

Unpack a backup as the corpus, refusing to write over one.

Usage:

kennis backup restore [OPTIONS] ARCHIVE

Options:

Name	Type	Description	Default
`--to`	path	Where the corpus is restored. The configured corpus by default.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis cite¶

Cite passages: each one's citation, its link and its reference.

A PASSAGE is a search hit's handle and chunk as it prints them (both words): id=X chunk=N or a project's path=P chunk=N; a kennis:// link; or a handle - an identifier, a title, a citekey, a DOI - for the whole document. The citation names the figure, table, equation or section the passage is in where the document shows one, and the link opens the passage with kennis open.

Usage:

kennis cite [OPTIONS] PASSAGE...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis config¶

Settings, credentials, and the guided setup.

Usage:

kennis config [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis config get¶

One setting's value, or every setting when no key is given.

Usage:

kennis config get [OPTIONS] [KEY]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis config init¶

Set kennis up, asking only what depends on you.

Re-runnable: every question offers what is currently in effect, so pressing return throughout keeps every value. Either way the whole file is written, every setting included, and an existing one is replaced only once you say so.

Usage:

kennis config init [OPTIONS]

Options:

Name	Type	Description	Default
`--defaults`	boolean	Write the configuration file without asking anything.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis config path¶

Where the configuration file lives.

Usage:

kennis config path [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis config set¶

Change one setting.

Validated through the same path the setup uses, so a value this accepts is one load_settings will accept on the next command rather than one that fails somewhere else later.

Usage:

kennis config set [OPTIONS] KEY VALUE

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis config show¶

Print the configuration, as valid TOML.

The warning goes to stderr, so kennis config show > config.toml produces a usable file rather than one with a warning in the middle. That is the same rule that keeps serve off stdout.

A file that sets nothing is treated as no file. "Is there a file" was never the question a reader is asking; "are any settings set" is. A 0-byte config.toml - which a setup where every answer was left unchanged used to write - otherwise made this command print nothing at all.

The note comes after the body. It is sixty lines of TOML, so a leading note is off the top of the terminal before the command has finished printing, and a reader looks at the end.

The body is styled rather than printed plain, because sixty lines in one colour is read by nobody. rich drops colour when stdout is not a terminal, so the redirect above still writes a file with no escape codes in it.

Usage:

kennis config show [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context¶

The knowledge bundle for the project you are standing in.

Usage:

kennis context [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context add¶

List a project kennis has not touched yet: a folder holding a .context/ bundle, or the bundle itself.

Usage:

kennis context add [OPTIONS] FOLDER

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context delete¶

Delete a project's .context/ folder and take it off the list.

kennis cannot undo this. The bundle is in the project's own repository, which kennis keeps no history of: what was committed there comes back with git, and nothing else does. kennis context forget unlists a project and leaves its folder.

Usage:

kennis context delete [OPTIONS] NAME

Options:

Name	Type	Description	Default
`-y`, `--yes`	boolean	Do not ask first.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context forget¶

Take a project off the list. Its files are not touched; kennis lists it again the next time it touches its bundle.

Usage:

kennis context forget [OPTIONS] NAME

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context index¶

Build this project's context index.

BM25 only, and offline. Design section 13: a bundle index that embedded would turn setting a project up from a 40ms scaffold into a model download, and the bundle is small enough that lexical search over it is the right answer rather than a concession.

The index is not committed. context init writes a .gitignore that keeps it out of the repository, because it is derived from the documents beside it and specific to whoever built it - their chunk settings, and their embedding model if they configured one. A clone gets the documents and runs this command once.

Usage:

kennis context index [OPTIONS]

Options:

Name	Type	Description	Default
`--project`	text	Index another known project's context, as `kennis context list` names it, rather than this one's.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context init¶

Create this project's .context/ bundle.

Where it goes is not always where you are. A bundle belongs at the root of a workspace, so this walks up to the nearest .git and creates it there; running the command three directories deep should not bury it there. The path is reported for that reason. --here overrides it.

Re-runnable, and converging rather than merely not-failing: a scaffold file that was deleted is written again, and anything you added is left alone.

Usage:

kennis context init [OPTIONS]

Options:

Name	Type	Description	Default
`--here`	boolean	Create it in the working directory instead of the workspace root.	`Sentinel.UNSET`
`--pack`	text	A pack this project uses; repeat for several. See `context packs`.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context list¶

Every project on this machine whose context kennis knows of.

A project is listed once kennis has touched its bundle - made it, remembered into it, indexed, synced or searched it - or once it is added. One whose folder has gone stays listed as missing until it is forgotten, because a disk that is not mounted is not a project that was deleted.

Usage:

kennis context list [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context packs¶

The packs this project uses: shown with no arguments, added to with some.

A project holds a copy of the context of the packs it declares, made by kennis context sync, so the stimela pack's advice reaches the projects that use stimela and no others. The declaration is in .context/bundle.json, committed with the project, so whoever clones it declares the same packs. The ids given are added to the declaration, never put in place of it, so a command printed for one pack cannot drop another; --drop removes one and --none clears it.

Usage:

kennis context packs [OPTIONS] [ID]...

Options:

Name	Type	Description	Default
`--drop`	text	Stop using this pack.	`Sentinel.UNSET`
`--none`	boolean	Declare no packs.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context reset¶

Remove the index and anything kennis owns, keeping your own files.

A file kennis owns is one a pack applied - owner: pack:<id> in its frontmatter. Everything remember --context writes is marked owner: user, and so is anything you wrote by hand, including a file with no frontmatter at all, so a reset leaves all of it.

Renaming a file to a dot-prefixed name keeps it out of the index; it does not make it yours, and a reset removes it if a pack owns it. LANDING.md and .skeleton.md are kept whatever they say, because they are yours to maintain and context init restores either one.

A file with a header kennis cannot read counts as yours. The two mistakes do not cost the same.

Usage:

kennis context reset [OPTIONS]

Options:

Name	Type	Description	Default
`-y`, `--yes`	boolean	Do not ask first.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context status¶

What this project's context holds, and whether its index is in step.

The same question corpus status answers, one scope down - and the freshness half is answered differently, because there is no commit to diff against. kennis does not write to your repository, so the index records no commit and the comparison is made against the document digests the index stored instead.

Usage:

kennis context status [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis context sync¶

Copy the context of the packs this project declares into its bundle.

Each pack's files land at the addresses the pack gives, owned by the pack, and a new release replaces a copy nobody edited. A file whose owner is user is never touched: to keep a pack's file as your own, set owner: user in its header. A copy you edited without doing so is left as it is and named. A pack this project stops declaring leaves its copies until you sync with --remove-undeclared.

Offline, and kennis does not commit: the bundle is in your repository, and what changed is a diff you can read before you commit.

Usage:

kennis context sync [OPTIONS]

Options:

Name	Type	Description	Default
`--remove-undeclared`	boolean	Also remove the unedited copies of packs this project no longer declares.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus¶

The machine-global document corpus.

Usage:

kennis corpus [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus add¶

Add files, directories or URLs to one collection.

Usage:

kennis corpus add [OPTIONS] IDENTIFIERS...

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes`)	Where the documents are written. One collection, never all.	`Sentinel.UNSET`
`-n`, `--notes`	boolean	Shorthand for notes.	`Sentinel.UNSET`
`-l`, `--literature`	boolean	Shorthand for literature.	`Sentinel.UNSET`
`-d`, `--docs`	boolean	Shorthand for docs.	`Sentinel.UNSET`
`--title`	text	Title for a single document, overriding what is found.	`Sentinel.UNSET`
`--group`	text	Subdirectory within the collection.	`Sentinel.UNSET`
`--keep-original` / `--no-keep-original`	boolean	Retain the source bytes beside the markdown.	None
`--identifier`	text	arXiv id, DOI or bibcode. Literature only.	`Sentinel.UNSET`
`--citekey`	text	Citekey to use instead of a derived one.	`Sentinel.UNSET`
`--project`	text	The docs project a page belongs to. Docs only.	`Sentinel.UNSET`
`--version`	text	Which version of the documentation the pages are, such as 2.12 or latest. Read from the address when not given. Docs only.	`Sentinel.UNSET`
`--refresh`	boolean	Ask the site again for each page already held, and update one that changed. Docs only.	`Sentinel.UNSET`
`--max-pages`	integer	N/A	`300`
`--max-depth`	integer	N/A	`5`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus copy¶

Make your own version of a document: a new note of yours.

For what kennis obtained - a pack's note, a documentation page - which is not edited in place: the copy has its own identifier, records what it was copied from, and is yours to change. The original is untouched.

Usage:

kennis corpus copy [OPTIONS] HANDLE

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes`)	Look only here. All three by default.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus history¶

What kennis did to this corpus, newest first.

Usage:

kennis corpus history [OPTIONS]

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes`)	Only commits touching this collection.	`Sentinel.UNSET`
`--limit`	integer	N/A	`20`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus index¶

Build the search index for one collection or all of them.

Usage:

kennis corpus index [OPTIONS]

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes`)	Only this collection. All three by default.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus init¶

Create the corpus and start its history.

Usage:

kennis corpus init [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus list¶

Every document in the corpus.

Usage:

kennis corpus list [OPTIONS]

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes`)	Only this collection. All three by default.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus move¶

Relocate or rename a document, keeping its identifier.

Usage:

kennis corpus move [OPTIONS] HANDLE

Options:

Name	Type	Description	Default
`--group`	text	The subdirectory to move it into. Empty for the root.	`Sentinel.UNSET`
`--title`	text	A new title, which renames the file with it.	`Sentinel.UNSET`
`--collection`	choice (`literature` \| `docs` \| `notes`)	Look only here. All three by default.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus remove¶

Delete a document, and its assets when it has any, or every page of one version of a docs project.

Usage:

kennis corpus remove [OPTIONS] [HANDLE]

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes`)	Look only here. All three by default.	`Sentinel.UNSET`
`--project`	text	With --version: remove that version of a docs project, every page of it.	`Sentinel.UNSET`
`--version`	text	With --project: the docs version to remove.	`Sentinel.UNSET`
`-y`, `--yes`	boolean	Do not ask first.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus restore¶

Put a document back as it was at a commit.

Usage:

kennis corpus restore [OPTIONS] DOCUMENT_ID

Options:

Name	Type	Description	Default
`--commit`	text	Restore from here.	`HEAD`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus return¶

Make the corpus's documents as they were at a point in its history.

COMMIT is a point kennis corpus history lists. Anything not yet recorded is recorded first, and the return is itself recorded, so returning to the point before it undoes it. The index is left as built: rebuild it to search what is held afterwards.

Usage:

kennis corpus return [OPTIONS] COMMIT

Options:

Name	Type	Description	Default
`-y`, `--yes`	boolean	Do not ask first.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus status¶

What the corpus holds, and what has changed since kennis last looked.

Usage:

kennis corpus status [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus sync¶

Converge the corpus with every installed pack.

Three sections, materialised three ways. A pack's notes are already in this machine's store, put there by kennis pack install, so they are copied. Its papers are fetched by identifier and its documentation sites are crawled, so this command uses the network - which kennis pack install deliberately does not.

Nothing you own is touched. A pack's note you edited is put back as the pack has it, and your edit kept as a new note of yours, so none is lost. A paper that cannot be fetched is reported and tried again next time, rather than stopping the run.

Usage:

kennis corpus sync [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus tree¶

The corpus as the directories it really is, with each document's handle.

The identifiers come from survey, which reads them as plain YAML keys and so still has one for a document that fails validation. That is deliberate: a tree is a picture of what is on disk, and a document kennis cannot read is exactly the one a reader needs to be shown.

Usage:

kennis corpus tree [OPTIONS]

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes`)	Only this collection. All three by default.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis corpus version¶

List the versions of each docs project held, or choose the one a search uses by default.

With no argument, every project; with a project, its versions; with a project and a version, that version becomes the one searched unless a search names others with --version.

Usage:

kennis corpus version [OPTIONS] [PROJECT] [VERSION]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis gui¶

Open kennis in a browser tab.

The window is served by the kennis service for this corpus, on the loopback interface only, on a port the operating system chooses, with a token in the address. Loopback is not private on a shared machine, which is what the token is for. The service is started if it is not running.

Usage:

kennis gui [OPTIONS]

Options:

Name	Type	Description	Default
`--no-browser`	boolean	Print the address and open nothing. For use over `ssh -L`.	`Sentinel.UNSET`
`--replace`	boolean	Stop the kennis service and start another before opening.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis link¶

Whether a clicked kennis:// link opens kennis, for this account.

Usage:

kennis link [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis link register¶

Make a clicked kennis:// link open the kennis window.

On Linux, a desktop entry made the default for the scheme; on Windows, a URL protocol in this account's registry. It runs this installation of kennis by its full path, so register again after moving it, and run kennis link remove before uninstalling, which removes nothing itself.

Usage:

kennis link register [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis link remove¶

Undo kennis link register. A kennis:// handler that another program registered is left alone.

Usage:

kennis link remove [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis open¶

Open a document in the kennis window, at a chunk.

LINK_OR_HANDLE is a kennis:// link, as a citation or a search hit carries - to a corpus document, a project's context file or a pack's - or anything kennis read takes: an identifier, a title, a citekey, a DOI. The service is started if it is not running. A kennis window already open shows it; otherwise a browser tab opens.

Usage:

kennis open [OPTIONS] LINK_OR_HANDLE

Options:

Name	Type	Description	Default
`--chunk`	integer range (`0` and above)	Mark this chunk, as a search hit's `chunk=` gives it. A link names its own.	None
`--collection`	choice (`literature` \| `docs` \| `notes`)	Look only here. All three collections by default.	`Sentinel.UNSET`
`--no-browser`	boolean	Print the address and open nothing.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack¶

Author and check a pack of knowledge.

Usage:

kennis pack [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack add¶

Declare papers, documentation, notes or context in a pack file.

Anything kennis corpus add takes, and each input is added or refused on its own as there. A local file or folder is copied into the pack under files/ and named relative to the pack file, so the pack still works on another machine; a context file already in the pack is declared by its folder with an include: naming it. The file is edited in place - comments and layout stay - and its generated block is brought up to date.

Usage:

kennis pack add [OPTIONS] INPUTS...

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes` \| `context`)	What the entries are. One kind, never several.	`Sentinel.UNSET`
`-n`, `--notes`	boolean	Shorthand for notes.	`Sentinel.UNSET`
`-l`, `--literature`	boolean	Shorthand for literature.	`Sentinel.UNSET`
`-d`, `--docs`	boolean	Shorthand for docs.	`Sentinel.UNSET`
`-c`, `--context`	boolean	Shorthand for context.	`Sentinel.UNSET`
`--title`	text	Title for a single document, overriding what is found.	`Sentinel.UNSET`
`--group`	text	Subdirectory within the pack's folder of the collection.	`Sentinel.UNSET`
`--identifier`	text	arXiv id, DOI or bibcode. Literature only.	`Sentinel.UNSET`
`--citekey`	text	Citekey to use instead of a derived one.	`Sentinel.UNSET`
`--project`	text	The docs project a page belongs to. Docs only.	`Sentinel.UNSET`
`--version`	text	Which version of the documentation the pages are, such as 2.12 or latest. Read from the address when not given. Docs only.	`Sentinel.UNSET`
`--pack`	file	The pack file. The one *.ken.yml here when not given.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack format¶

Write every entry of a pack file the way kennis writes one.

Each entry becomes a mapping in braces with one key per line, a paper's identifier first and its authors last, as a list, and entries are set apart by a blank line. Comments between entries are kept; a comment inside an entry is not. A pack whose authors are one string, as kennis wrote them before, is made readable again by this.

Usage:

kennis pack format [OPTIONS]

Options:

Name	Type	Description	Default
`--pack`	file	The pack file. The one *.ken.yml here when not given.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack init¶

Scaffold a new .ken.yml.

The line at the top is the point of the command. It points an editor at kennis's published JSON Schema, so an author gets completion and inline errors while writing the pack - with kennis not installed at all.

Writes <id>.ken.yml in the working directory unless a path is given, and refuses an existing file: a pack holds declarations kennis did not write and cannot restore.

Usage:

kennis pack init [OPTIONS] [PATH]

Options:

Name	Type	Description	Default
`--id`	text	The pack's slug, stable forever.	`Sentinel.UNSET`
`--name`	text	What the pack is called, for a reader.	`Sentinel.UNSET`
`--pack-version`	text	The pack's own version, which `pack status` reports.	`0.1.0`
`--description`	text	A sentence or two. It reaches a model, not only a reader.	None
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack install¶

Install a pack into this machine's store.

Meant to be called by the provider, from its own sync command, on every run: boepie sync ends by handing kennis the path to its own .ken.yml. Calling it repeatedly is cheap - a pack whose file and store both check out is recognised and nothing is rewritten.

No network, and nothing is materialised into the corpus yet: this records what the provider declared. corpus sync and context sync converge the documents with it, and neither is built.

Usage:

kennis pack install [OPTIONS] PATH

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack list¶

Every pack installed on this machine.

The listing is the whole answer, so it is a listing and not a report: the pack id leads, because it is the column you copy out of and hand to pack uninstall.

--json is for a provider asking whether its pack is held, so the rows stay free to change for a person (#401 reversed). No corpus is still a failure rather than an empty document, because "kennis cannot answer" and "kennis holds nothing" lead a provider to different things.

Usage:

kennis pack list [OPTIONS]

Options:

Name	Type	Description	Default
`--json`	boolean	Print one JSON document for a program to read, instead of rows.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack remove¶

Take entries out of a pack file.

Each name is a citekey, an identifier, an address, a documentation project, a shipped file's path, a source folder, or a context file its folder's include: names. A copy pack add made under files/ that no entry names any more is deleted; nothing else in the pack is.

Usage:

kennis pack remove [OPTIONS] NAMES...

Options:

Name	Type	Description	Default
`--pack`	file	The pack file. The one *.ken.yml here when not given.	`Sentinel.UNSET`
`-y`, `--yes`	boolean	Do not ask first.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack show¶

What each installed pack contains: its papers, documentation projects, notes and context files.

With no PACK_ID, every installed pack. A PACK_ID that is not installed is refused before anything is printed, naming kennis pack list.

Usage:

kennis pack show [OPTIONS] [PACK_ID]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack status¶

What each installed pack recorded, and where two of them collide.

The overlaps are the reason this command exists. Two packs declaring the same paper or the same documentation project is resolved silently, by whichever was installed first, and a resolution nobody is told about is one nobody can correct. Reported here every run rather than once, inside an automated provider run nobody reads.

Usage:

kennis pack status [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack uninstall¶

Drop a pack from this machine's store.

It reaches the store and nothing else. Documents already in the corpus stay, and so does this pack's content in any project you have checked out - kennis keeps no registry of your projects, so it cannot reach them. They converge when each one is next synchronised.

Usage:

kennis pack uninstall [OPTIONS] PACK_ID

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack update¶

Recompute a pack's generated block from the content it names.

A paper declared without a citekey is described here, as corpus add would describe it - looked up on arXiv or at its DOI's registry - and the citekey, title, authors and year it lacks are written into its entry, so every machine files it alike. An entry with a citekey is not looked up.

Run this after changing any file the pack ships, and before pack validate. A pack whose digests disagree with its files is believed on kennis's fast path, so the block is what makes the pack honest about itself.

A run that finds nothing changed leaves the file byte-identical, so calling it on every release build is free.

Usage:

kennis pack update [OPTIONS] PATH

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis pack validate¶

Check a .ken.yml file against kennis and against its own content.

Meant for a release pipeline. A pack that ships without this having passed can declare digests that disagree with the files beside them, and kennis believes a pack's own digests on the fast path - so the check that keeps that honest is this one, run where the pack is built.

Exits non-zero when anything is wrong, so a pipeline stops.

Usage:

kennis pack validate [OPTIONS] PATH

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis read¶

Print a document, or the passage around one of its chunks.

HANDLE is anything that names the document: its identifier, its title, the filename it has on disk with or without the extension, a paper's citekey or arXiv identifier or DOI, a docs page's project/page. The same resolution corpus remove and corpus move use, so a handle that works for one works for all of them.

Without --chunks the document is read from the corpus, not from the index, and a document that has never been indexed is still readable. With --chunks the passage is stitched out of the index, which is what a search hit's coordinates address - so that one, and only that one, needs kennis corpus index to have run.

--chunks is a python slice over the document's own chunks: 3 is one, 0:3 is the first three, 2: runs to the end, -1 is the last. There is no step, because a passage that is not contiguous is not a passage. It is an option value rather than a bracket on the handle (read x[0:3]) because [ and ] are glob characters: the shell rewrites an unquoted bracket expression against whatever files are in the working directory, silently, and differently from one directory to the next. Concern #205.

One output contract either way: stdout is the text, stderr is the provenance. kennis read x > x.md and kennis read x --chunks 3 | less both get the markdown and nothing else. A contract that changed with a flag would put a report line on the front of one of them.

Usage:

kennis read [OPTIONS] HANDLE

Options:

Name	Type	Description	Default
`--collection`	choice (`literature` \| `docs` \| `notes` \| `context`)	Look only here. All three corpus collections by default.	`Sentinel.UNSET`
`--chunks`	text	Read these chunks instead of the whole document, python-style: '3', '0:3', '2:', ':3', '-1'. No step - a passage is contiguous.	None
`--frontmatter`	boolean	Include the document's YAML frontmatter in the output.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis remember¶

Write something down, into notes or this project, and index it.

--context writes into the workspace, not the corpus. Notes are machine-global; a .context/ bundle belongs to one project and is committed with it. Either way the file is marked owner: user, so no pack and no sync will ever overwrite it.

Usage:

kennis remember [OPTIONS] [TEXT]

Options:

Name	Type	Description	Default
`--from`	file	Read the text from this file instead of the argument.	`Sentinel.UNSET`
`--title`	text	Title for the note, overriding its first line.	`Sentinel.UNSET`
`--group`	text	Subdirectory within the collection or bundle.	`Sentinel.UNSET`
`--context`	boolean	Write into this project's .context/ bundle instead of notes.	`Sentinel.UNSET`
`--no-index`	boolean	Write the note without rebuilding the notes index.	`Sentinel.UNSET`
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis search¶

Search the corpus and this project's context, and print the best passages.

context is a scope, not a separate command. The question a reader is answering is which scopes to look in - this project, the machine, or both - and that is one question, so it is one option. Without --collection every scope that has an index is searched.

A scope you name is a promise and a scope you did not is not: asking for context outside a project is an error, while a sweep that finds no bundle simply reports what it did search.

Usage:

kennis search [OPTIONS] QUESTION

Options:

Name	Type	Description	Default
`--collection`	text	Comma-separated scopes to search: context, literature, docs, notes, all. 'context' is this project's bundle.	`all`
`-k`, `--top-k`	integer	How many hits to show.	None
`--mode`	choice (`hybrid` \| `dense` \| `bm25`)	Retrieval method, overriding retrieval.corpus_method and retrieval.context_method. Falls back to bm25 against a lexical index.	None
`--group`	text	Restrict to documents filed under a group, shell-style: 'botany', 'physics/'. Quote it - your shell expands an unquoted '' first.	`Sentinel.UNSET`
`--project`	text	Docs only: an alias for --group, since a page's project is its group.	`Sentinel.UNSET`
`--version`	text	Docs versions to search, repeatable: '2.12', 'pydantic=2.12', or 'all'. Each project's current version without it.	`Sentinel.UNSET`
`--all-projects`	boolean	Search every project's context that `kennis context list` knows, not only this project's.	`Sentinel.UNSET`
`--snippet`	choice (`none` \| `short` \| `full`)	How much of each hit's text to show.	`short`
`--scores`	choice (`human` \| `raw` \| `none`)	How well each hit matched: a level, the raw per-leg numbers, or nothing. Default: the setting retrieval.scores, human unless changed.	None
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis serve¶

Run the MCP server, speaking JSON-RPC on stdin and stdout.

Started by an agent rather than by hand - Claude Code, VS Code, Copilot - which is why it prints nothing: standard output is the protocol.

The server describes what this machine holds, built from the packs installed now, so an agent is told about the knowledge that is actually here rather than about kennis in the abstract.

Usage:

kennis serve [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis service¶

The kennis service that owns this corpus while it runs.

Usage:

kennis service [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis service status¶

Whether the service runs for this corpus, where it listens, and the tasks it has not finished.

The address is printed without its token: the token is in the service's record, readable by this account alone.

Usage:

kennis service status [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis service stop¶

Stop the service, unless it is running a task.

A task stopped part way keeps nothing of what it did, so the service refuses rather than throw that work away, and keeps running.

Usage:

kennis service stop [OPTIONS]

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`

kennis service watch¶

Follow a task to its end: one a command stopped watching, after Ctrl-Z or a second Ctrl-C, which goes on in the service. Ctrl-C here cancels it.

Usage:

kennis service watch [OPTIONS] TASK

Options:

Name	Type	Description	Default
`-h`, `--help`	boolean	Show this message and exit.	`Sentinel.UNSET`