Thin CLI for the Cairn local-first file-organization harness: scriptable file ops, a local HTTP API (serve), and the MCP server launcher.
Project description
cairn-cli
A thin command-line interface over cairn-core. Standard-library only.
uvx cairn --workspace ~/Documents/notes ls
Commands
cairn [--workspace DIR] [--json] <command>
ls [path] list a directory
tree [path] show the file tree
read <path> print a file (flattened .uni text)
create <path> [content] create a file ('-' reads stdin)
mkdir <path> create a folder
mv <path> <target_dir> move a file/folder
rename <path> <new_name> rename in place
rm <path> delete
edit <path> <old> <new> replace a unique occurrence
import <path> [--all] convert docx/pdf/pptx/csv/xlsx/md into .uni
grep <pattern> [path] search file contents
find <query> [path] search file names
tag <path> [tags...] get (no args) or set tags
tags show the workspace tag tree
retrieve <query> [-k N] find relevant documents
serve [--host H --port N] run the local HTTP API (contract for the web UI)
mcp run the MCP server (stdio) for Claude Code / Codex
--json makes any command emit machine-readable JSON.
Examples
export CAIRN_WORKSPACE=~/Documents/notes
cairn tree
echo "meeting notes" | cairn create inbox/2026-07-16.uni -
cairn tag inbox/2026-07-16.uni meetings q3
cairn retrieve "budget planning" -k 5
cairn serve # http://127.0.0.1:4177/api/health
Three faces, one core
cairn (this CLI), cairn-mcp-server (the MCP server), and the planned web UI
are all thin adapters over cairn-core, so they can never drift. Use the
CLI for scripting, mcp inside Claude Code / Codex, and serve to back the
web UI.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cairn_cli-0.2.1.tar.gz.
File metadata
- Download URL: cairn_cli-0.2.1.tar.gz
- Upload date:
- Size: 7.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7b358051723218280644780f695d88415c65d839615b7757418007a7f410d403
|
|
| MD5 |
562fa312291fab4880c92042f46c3556
|
|
| BLAKE2b-256 |
178769230124631a3eea7c887d61ecd6afba935547b76009d652eca148858b8c
|
File details
Details for the file cairn_cli-0.2.1-py3-none-any.whl.
File metadata
- Download URL: cairn_cli-0.2.1-py3-none-any.whl
- Upload date:
- Size: 8.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
08aa00197e84a7c08c0452e7d3fe5f7cdf28f813b2c189ef4912c55d8a510dcc
|
|
| MD5 |
2a0de63b65199a32023b1484ee2d5c15
|
|
| BLAKE2b-256 |
b28b3c36430281bbd33c4428e7e6ab13c2a27fbd725ac57d463b17e30786e22f
|
