# The kribble CLI > 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. ## Install 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: :::tabs{group="os"} ::tab{label="macOS and Linux"} ```bash curl -fsSL https://kribble.example.com/install.sh | sh ``` It 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. :: ::tab{label="Windows"} ```powershell irm https://kribble.example.com/install.ps1 | iex ``` It 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: :::tabs{group="os"} ::tab{label="macOS and Linux"} ```bash curl -fsSL https://getkribble.com/install.sh | sh ``` :: ::tab{label="Windows"} ```powershell irm https://getkribble.com/install.ps1 | iex ``` :: ::: Check the installation with `kribble version`. ## Sign in ```bash kribble login ``` The 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 | | --- | --- | | `--server URL` | The server to sign in to, when the CLI doesn't know it yet | | `--read-only` | Ask for read access only | | `--token TOKEN` | Use an access token instead of the browser; `--token -` reads it from standard input | | `--no-browser` | Print the approval link instead of opening a browser, for example over SSH | | `--profile NAME` | Sign in to this profile | `kribble status` shows the profile, server, account and versions in use, and whether the login still works. ### Without signing in 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. ### Profiles Each saved server or account is a named profile, such as `work` and `personal`. ```bash 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 acme ``` `kribble 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](../using-kribble/the-desktop-app.md) shares the same profiles. ### Settings and environment variables 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 | | --- | --- | | `KRIBBLE_URL` | The server, instead of the saved one | | `KRIBBLE_TOKEN` | The access token, instead of the saved one | | `KRIBBLE_PROFILE` | The profile, instead of the saved default | | `KRIBBLE_CONFIG` | 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](../using-kribble/ai-agents.md) for the scopes) and set both. ## Paths 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). ## Commands `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. ### Notes | Command | What it does | | --- | --- | | `kribble ls [SPACE[/FOLDER…]] [-r] [--json]` | Lists your spaces, or the notes in a space or folder; `-r` shows everything below as a tree | | `kribble read NOTE [--version N] [--json]` | Prints a note as markdown; `--version` an earlier version; `--json` adds its id, path and version | | `kribble search QUERY [--org ORG] [--limit N] [--json]` | Searches notes, with the same operators as the search box (see Search below) | | `kribble search --local [--dir DIR] QUERY` | Searches the markdown files in a directory, without a server | | `kribble edit NOTE --old TEXT --new TEXT [--all] [--base-version N]` | Replaces exact text in a note: the safest way to change one | | `kribble write NOTE [FILE\|-] (--base-version N \| --force)` | Replaces a note's whole content from a file or standard input | | `kribble new PATH [FILE\|-] [--folder] [--description TEXT]` | Creates a note (or with `--folder` a folder), and any missing parent folders | | `kribble mv NOTE DESTINATION` | Moves or renames a note; DESTINATION is the full new path | | `kribble set NOTE [--name N] [--description D] [--icon I] [--first \| --last \| --before SIBLING \| --after SIBLING]` | Changes a note's or folder's name, description, icon (a Lucide icon name) or place among its siblings | | `kribble rm NOTE [-r]` | Deletes a note; `-r` for one with children. This can't be undone | | `kribble history NOTE [--json]` | Lists a note's versions, with who saved them and through which token | | `kribble open NOTE\|FILE [--app] [--print]` | Opens a note in the browser, or with `--app` in the [desktop app](../using-kribble/the-desktop-app.md); `--print` prints the link. Takes a pulled file too | | `kribble diff NOTE [--from N] [--to M]` | Shows what changed in a note, by default its latest change | | `kribble changes [--since 24h] [--by token\|agents\|anyone] [--diff]` | Lists notes changed lately, by default through this computer's token; `--diff` shows the changes | | `kribble pull "Space" \| "Space/Folder" [DIR] [--org ORG]` | Pulls a space, folder or note as markdown files (see Working copies below) | | `kribble push [DIR] [--to "Space" \| "Space/Folder"] [--org ORG] [--dry-run] [--adopt] [--delete] [-q]` | Pushes a working copy's changes, or a repository's docs folder | | `kribble init [DIR] [--to "Space" \| "Space/Folder"] [--org ORG]` | Writes the `kribble.toml` that says where `kribble push` puts a docs folder | | `kribble export "Space" \| "Space/Folder" DIR [--org ORG]` | Writes a space or folder as markdown files, to move it into a repository | | `kribble comments NOTE [--all] [--json]` | Lists a note's open comment threads; `--all` adds resolved ones | | `kribble comment NOTE TEXT [--quote "text in the note"]` | Comments on a note, or with `--quote` on a passage of it | | `kribble reply THREAD TEXT [--resolve]` | Replies to a thread, and resolves it with `--resolve` | | `kribble resolve THREAD [--reopen]` | 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: ```bash kribble read "Engineering/Plans/Q3" --json # {"info": {"version": 7, …}, "markdown": …} kribble write "Engineering/Plans/Q3" new.md --base-version 7 ``` If 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](../using-kribble/comments-and-reviews.md). ### Search `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](../using-kribble/search.md) 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: ```bash 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 day ``` For 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. ### Search markdown files offline `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](../using-kribble/search.md)). ```bash 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. ### Sites | Command | What it does | | --- | --- | | `kribble sites [PATH] [--json]` | Lists the published sites you can reach, or the one of a space, folder or note, with URL and build status | | `kribble targets [SPACE] [--json]` | Lists where sites can be published to, and what each target takes | | `kribble deploy PATH [--target …] [--slug S] [--access public\|space_members] [--wait]` | Publishes a space, folder or note as a site, or builds it again if it is published | | `kribble redeploy PATH\|SITE_ID [--wait]` | Builds a published site again with its settings | All the options, and publishing from CI, are in [Publishing sites](../using-kribble/publishing-sites.md). ### Markdown | Command | What it does | | --- | --- | | `kribble fmt [-w \| --check] [FILE…]` | Rewrites Kribble markdown in its canonical form: to standard output, in place with `-w`, or lists the files that aren't canonical with `--check`. Without files it reads standard input | | `kribble check [FILE…]` | 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](../using-kribble/writing-notes.md), and `kribble skill` prints a summary. ### Setup | Command | What it does | | --- | --- | | `kribble login` | Signs in (see above) | | `kribble logout` | Forgets the saved access token | | `kribble status` | Shows the server, account and versions in use; inside a working copy, its local changes first | | `kribble setup --server URL` | Saves the server address without signing in (the installer uses it) | | `kribble version [--short]` | Prints the CLI's version, and the server's when signed in | | `kribble help [command]` | Shows help | | `kribble profile …` | Manages profiles (see above) | | `kribble update [--force]` | Updates the CLI (see Updates below) | ### Agents and editors | Command | What it does | | --- | --- | | `kribble mcp install [claude\|claude-code\|claude-desktop\|codex\|all] [--docs URL]` | Connects Claude Code, Claude Desktop and Codex to Kribble, or with `--docs` to a published documentation site | | `kribble mcp uninstall [same]`, `kribble mcp status` | Removes that again; shows what is set up | | `kribble mcp serve`, `kribble mcp docs URL` | The MCP servers the apps start (stdio) | | `kribble skill [--install claude\|agents] [--project]` | Prints the guide for AI agents, or installs it where agents look for it | | `kribble extension install EDITOR`, `kribble extension list` | Installs the Kribble markdown editor into VS Code and its forks or JetBrains IDEs | [AI agents](../using-kribble/ai-agents.md) explains `mcp` and `skill`. ## Working copies: pull, edit, push 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. ```bash 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 Kribble ``` The 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. ### The files Each note is a `.md` file that starts with front matter: ```markdown --- 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 `![](./_assets/diagram.png)`. - 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. ### Merges and conflicts 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: ```text <<<<<<< yours Your version of the lines ======= The version in Kribble >>>>>>> kribble ``` Edit 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. ## Push a repository's docs 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`): ```bash kribble init docs --to "Engineering/SDK" # or --to "SDK docs" for a whole space ``` ```toml # docs/kribble.toml folder = "Engineering/SDK" org = "Acme" # only needed when your login reaches several organisations ``` ```bash kribble push docs --dry-run # what would change kribble push docs # or: kribble push docs --to "Engineering/SDK" --org Acme ``` The 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](../using-kribble/publishing-sites.md). ### Move docs from Kribble into a repository ```bash 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. ## Updates ```bash kribble update ``` The 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`. ## Editor extensions 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. ```bash 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.