Install the kribble command, sign in, and read, edit, pull, push and publish notes from the terminal
kribble is Kribble's command-line tool. It reads and changes notes as markdown, pulls folders as files to work on with any editor and pushes them back, pushes a repository's docs, publishes sites, and connects AI agents and editors to Kribble. It is one file with no dependencies, for macOS, Linux and Windows.
Your Kribble server hands out the CLI in the version that matches it. Open CLI & agents (at the bottom of the sidebar, or in your user menu) for the command with your server's address filled in, or use the server's address yourself:
curl -fsSL https://kribble.example.com/install.sh | shIt installs kribble in ~/.local/bin, or /usr/local/bin when run as root. Set KRIBBLE_INSTALL_DIR to put it elsewhere. If the directory isn't on your PATH, the script says so.
irm https://kribble.example.com/install.ps1 | iexIt installs kribble.exe in %LOCALAPPDATA%\Programs\kribble (or KRIBBLE_INSTALL_DIR) and adds that folder to your PATH; open a new terminal to pick it up.
Installed from a server, the CLI remembers that server, so kribble login needs no address.
Without a Kribble server at hand (for example, to give your AI tools a published documentation site), install it from getkribble.com:
curl -fsSL https://getkribble.com/install.sh | shirm https://getkribble.com/install.ps1 | iexCheck the installation with kribble version.
kribble loginThe CLI shows a code and opens your server in the browser. Check that the page shows the same code, then choose:
Organization: All my organizations (including ones you join later) or only one.
Access: Read and write notes, or Read notes only.
Click Approve, and the terminal says Signed in. The CLI now acts as you, with your permissions in each organisation.
The login is an access token named "kribble CLI" with the computer's name. It is listed, and can be revoked, under Access Tokens in the settings of the organisation you chose, or of your personal organisation when you chose all of them. kribble logout forgets the token on this computer but doesn't revoke it.
Options of kribble login:
Option | Meaning |
|---|---|
| The server to sign in to, when the CLI doesn't know it yet |
| Ask for read access only |
| Use an access token instead of the browser; |
| Print the approval link instead of opening a browser, for example over SSH |
| Sign in to this profile |
kribble status shows the profile, server, account and versions in use, and whether the login still works.
These commands work without a login:
kribble fmt and kribble check, which only read local files.
kribble search --local, which searches markdown files on this computer (see Search markdown files offline below).
kribble mcp docs URL and kribble mcp install --docs URL, which read a public documentation site.
kribble skill, kribble help, kribble version, kribble profile and kribble mcp status.
kribble update, which updates from the saved server or, without one, from getkribble.com.
kribble extension install, which needs a saved server address (to download the extension from) but no login.
Everything else talks to the server and needs a login.
Each saved server or account is a named profile, such as work and personal.
kribble profile add work --server https://kribble.acme.com # sign in to a new profile
kribble profile # list them (--json for scripts)
kribble profile use work # the one commands use from now on
kribble ls --profile personal # another one for a single command
kribble profile rename work acme
kribble profile remove acmekribble profile use also switches the AI apps set up with kribble mcp install, from their next Kribble call. A folder pulled with kribble pull keeps using the profile it came from. The desktop app shares the same profiles.
The profiles and their tokens are saved in kribble/config.toml in your user configuration folder (~/.config on Linux, ~/Library/Application Support on macOS, %AppData% on Windows), readable only by you.
Variable | Effect |
|---|---|
| The server, instead of the saved one |
| The access token, instead of the saved one |
| The profile, instead of the saved default |
| Another settings file |
KRIBBLE_URL and KRIBBLE_TOKEN are the way to run the CLI in CI or on a server: create a token under Access Tokens (see AI agents for the scopes) and set both.
A note's path is Space/Folder/Note, with names as Kribble shows them, spaces and capitals included. Quote paths in the shell. Every command that takes a note also takes its id. When your login covers several organisations and two spaces share a name, kribble pull, push, export and init take --org (the organisation's name or id); elsewhere use the space's id (kribble ls --json shows it).
kribble help lists every command; kribble help COMMAND (or kribble COMMAND -h) explains one and its options. Every command takes --profile NAME, and options can go before or after the other arguments.
Command | What it does |
|---|---|
| Lists your spaces, or the notes in a space or folder; |
| Prints a note as markdown; |
| Searches notes, with the same operators as the search box (see Search below) |
| Searches the markdown files in a directory, without a server |
| Replaces exact text in a note: the safest way to change one |
| Replaces a note's whole content from a file or standard input |
| Creates a note (or with |
| Moves or renames a note; DESTINATION is the full new path |
| Changes a note's or folder's name, description, icon (a Lucide icon name) or place among its siblings |
| Deletes a note; |
| Lists a note's versions, with who saved them and through which token |
| Opens a note in the browser, or with |
| Shows what changed in a note, by default its latest change |
| Lists notes changed lately, by default through this computer's token; |
| Pulls a space, folder or note as markdown files (see Working copies below) |
| Pushes a working copy's changes, or a repository's docs folder |
| Writes the |
| Writes a space or folder as markdown files, to move it into a repository |
| Lists a note's open comment threads; |
| Comments on a note, or with |
| Replies to a thread, and resolves it with |
| Resolves a thread, or reopens it |
edit and write print a diff of the note after saving (--quiet doesn't). For text over several lines, edit takes --old-file and --new-file. --old must match exactly once; copy it from kribble read, or pass --all.
To replace a note without losing someone else's change, pass the version you read:
kribble read "Engineering/Plans/Q3" --json # {"info": {"version": 7, …}, "markdown": …}
kribble write "Engineering/Plans/Q3" new.md --base-version 7If the note changed in the meantime, the write fails; read it again and redo your change. --force overwrites whatever is there.
In comment commands, a TEXT of - reads the text from standard input. @Name in a comment notifies that person. See Comments and reviews.
kribble search takes the same query as the search box in the app, operators included: in:, org:, by:, updated:, title:, type:, sort:, "phrases" and -exclusions (Search lists them all). --org NAME is the same as org:NAME. Put the query in single quotes, so that the shell leaves the double quotes alone and doesn't read < and > as redirections:
kribble search 'rollback'
kribble search 'deploy in:Engineering by:me updated:<30d'
kribble search '"rate limit" -draft' --limit 50
kribble search 'updated:<1d sort:recent' # operators alone: what changed in the last dayFor each note it prints the name and path, then the headings that matched with the text around each match. --limit sets how many notes it shows (20 by default, at most 100), and --json prints the results with each note's id, path and the blocks that matched. If an in: or by: matches no space, folder or person, the command fails and says which, instead of printing nothing. Dates in updated: count in UTC here; the app uses your browser's time zone.
kribble search --local searches the markdown files under a directory instead of the server: a folder you pulled, or a repository's docs. It needs no server and no sign-in, and works offline. It matches your words as you type them; it doesn't find other forms of them the way the server's search does (see Search).
kribble search --local 'rollback' # under the current directory
kribble search --local --dir docs 'title:install' # under docs/It reads every .md and .markdown file under the directory, leaving out hidden directories (such as .git and .kribble), node_modules and _assets, so there is no index to keep up to date. A file's title is the name in its front matter, else a leading # Title, else the file name. Matches in the title count most, then headings, the description, the folder names and the text. Small typos are forgiven, words match the words they start, and code identifiers are found by their words, as on the server.
Each match is printed with the file and line of the section that matched best (docs/Deploying.md:42), its heading and the text around the match, so editors and agents can jump straight there. The query takes the same syntax, with these differences:
in: names folders under the directory: in:Guides or in:"Guides/Setup".
updated: and sort: use the files' modification times, in this computer's time zone.
type:folder finds nothing, as only files are searched.
by: is ignored, with a message: files don't say who wrote them.
Command | What it does |
|---|---|
| Lists the published sites you can reach, or the one of a space, folder or note, with URL and build status |
| Lists where sites can be published to, and what each target takes |
| Publishes a space, folder or note as a site, or builds it again if it is published |
| Builds a published site again with its settings |
All the options, and publishing from CI, are in Publishing sites.
Command | What it does |
|---|---|
| Rewrites Kribble markdown in its canonical form: to standard output, in place with |
| Reports markdown that Kribble would change or drop when it saves it; exits with status 1 if there is any |
Run kribble check on markdown you wrote or generated before you write it into a note or push it. The format itself is described in Writing notes, and kribble skill prints a summary.
Command | What it does |
|---|---|
| Signs in (see above) |
| Forgets the saved access token |
| Shows the server, account and versions in use; inside a working copy, its local changes first |
| Saves the server address without signing in (the installer uses it) |
| Prints the CLI's version, and the server's when signed in |
| Shows help |
| Manages profiles (see above) |
| Updates the CLI (see Updates below) |
Command | What it does |
|---|---|
| Connects Claude Code, Claude Desktop and Codex to Kribble, or with |
| Removes that again; shows what is set up |
| The MCP servers the apps start (stdio) |
| Prints the guide for AI agents, or installs it where agents look for it |
| Installs the Kribble markdown editor into VS Code and its forks or JetBrains IDEs |
AI agents explains mcp and skill.
For work across several notes, such as restructuring a folder or renaming a term everywhere, pull the notes as files, change them with any tool, and push the changes back.
kribble pull "Engineering/Plans" plans # notes → plans/*.md ("Engineering" alone: the whole space)
cd plans
# edit, grep, rename, add files…
kribble status # which files you changed
kribble diff # your changes, as a diff
kribble push # saves them in KribbleThe directory must be new or empty; without DIR, it is named after the folder. A pulled folder is a working copy: .kribble/ inside it records which file is which note and the versions you pulled. Inside it, kribble diff [FILE…] shows your local changes and kribble pull (with no arguments) brings in changes made in Kribble since.
Each note is a .md file that starts with front matter:
---
name: Rollout plan
description: How we move every region
icon: rocket
order: 2
---
The note's content, in Kribble markdown.name, description, icon (a Lucide icon name) and order (the place among its siblings) are the note's properties. Change them to rename, describe or reorder notes; after a push the file is renamed to follow the note's name.
A folder is a directory with a _folder.md that holds only its front matter.
Notes under a note are in a directory named like it: Setup.md and Setup/.
Images and attachments are in _assets/ next to the notes that use them, linked as .
Links between notes are relative links to the files, such as [the plan](../Plans/Rollout plan.md); put the path in <…> when it has spaces.
A new .md file becomes a new note, and a new directory a new folder; images it links to are uploaded. Deleting a file deletes its note only if you push with --delete; otherwise the note stays in Kribble.
When notes changed in Kribble since you pulled, kribble pull and kribble push merge those changes with yours, line by line. Where both sides changed the same lines, the file gets conflict markers:
<<<<<<< yours
Your version of the lines
=======
The version in Kribble
>>>>>>> kribbleEdit the file to keep the right text, remove the markers, and push again. A push refuses files that still have markers. A note deleted in Kribble that you edited locally is kept, and your push creates it again.
A project's docs can live in its repository as markdown, next to the code, and be pushed to Kribble, where people read and comment on them. The files have the same format as a working copy. A kribble.toml in the docs folder says where they go: a folder in a space, or a whole space. kribble init writes it, asking where (or pass --to):
kribble init docs --to "Engineering/SDK" # or --to "SDK docs" for a whole space# docs/kribble.toml
folder = "Engineering/SDK"
org = "Acme" # only needed when your login reaches several organisationskribble push docs --dry-run # what would change
kribble push docs # or: kribble push docs --to "Engineering/SDK" --org AcmeThe space or folder doesn't have to exist: the first push creates it (a new space needs permission to create spaces in the organisation). Pushed into a whole space, the space belongs to the repository: its notes are read-only in Kribble and nothing new can be added at its top level. A space that holds a folder another push manages can't be pushed into whole.
A push updates the notes in place, so their comments and history stay. It creates notes for new files, deletes notes whose files are gone, uploads the images the markdown links to, and prints a diff of each changed note (-q leaves the diffs out). It warns about markdown Kribble would change, so run kribble check on the files first.
The folder (or space) then belongs to the repository: Kribble shows the repository and commit it came from, and its notes are read-only in Kribble, though people can still comment. Read the comments with kribble comments, fix the markdown in the repository, and reply to the threads.
In CI, set KRIBBLE_URL and KRIBBLE_TOKEN and run kribble push docs. To rebuild a published site after the push, see Publishing sites.
kribble export "Engineering/SDK" docs # the files, and docs/kribble.toml
git add docs && git commit -m "Docs from Kribble"
kribble push docs --adopt--adopt ties the existing folder (or space) to the files: its notes keep their comments and history, and notes that aren't in the push are deleted. Later pushes need no flag.
kribble updateThe CLI updates to the version your server offers, so it stays in step with the server; without a saved server it takes the latest from getkribble.com. --force reinstalls even when the versions match. When you sign in to a server running another version, the CLI suggests kribble update. An update also refreshes the Claude Code skill if you installed it with kribble skill --install claude.
The Kribble markdown editor works inside your IDE, with the same blocks, callouts and tables as in Kribble. It is handy for a repository's docs.
kribble extension list # the editors kribble finds
kribble extension install vscode # or: cursor, windsurf, vscodium
kribble extension install jetbrains # every JetBrains IDE it finds
kribble extension install rider # or one: idea, pycharm, goland, webstorm, clion, …VS Code and its forks: the editor's command-line tool (code, cursor, windsurf or codium) must be on your PATH. After installing, open a .md file and choose Reopen Editor With… → Kribble.
JetBrains IDEs, 2026.2 or newer: they are found by their settings folders, which an IDE creates when it first starts, so they needn't be on your PATH. Restart the IDE to load the plugin, and run the command again to update it. Close the IDE first if the install fails.
The extensions download from your server, so the CLI needs a saved server address. Your server is also a JetBrains plugin repository: add https://kribble.example.com/downloads/jetbrains/updatePlugins.xml under Settings → Plugins → the gear icon → Manage Plugin Repositories, and the IDE installs and updates Kribble Markdown itself.