cairn
An archive for things you want to remember. Paste text or pictures in the browser, or save, search, tag, and change items from the CLI or over an HTTP API that agents can call. Everything, including the files, lives in one SQLite database.
Built with the same stack as twig (~/twig): Rust, Actix-web, maud, and
rusqlite (bundled), with personal access tokens modelled on twig's.
Quick start
With mise:
mise run run # cargo run -- serve, on 127.0.0.1:8080, DB in ./cairn.db
Create a sign-in (the password is generated and printed once):
cargo run -- user create silen
cargo run -- user reset silen # new generated password; the old one stops working
Open http://127.0.0.1:8080, sign in, and paste anything. Pictures can be pasted straight from the clipboard, or chosen with the file picker. Change your password on the Account page.
API and CLI access uses tokens. Create them on the Tokens page, or on the command line:
cargo run -- token create laptop # read + write
cargo run -- token create dashboard --read-only
cargo run -- token list
cargo run -- token revoke <id>
Configuration
| Variable | Default | Meaning |
|---|---|---|
BIND_ADDRESS | 127.0.0.1 | Address the server listens on |
PORT | 8080 | Port the server listens on |
DB_PATH | cairn.db | SQLite database file |
CAIRN_URL | https://cairn.silenlocatelli.ch | Server the CLI talks to. Set it to http://127.0.0.1:8080 for a local server |
CAIRN_TOKEN | — | Access token the CLI sends |
RUST_LOG | info | Log filter |
Items, metadata, and files
An item has a title, text content, tags, a metadata object, and any number of attachments:
- Text can be empty if the item has a title or files.
- Metadata is a JSON object with identifier keys (letters, digits,
_,-), for example{"source": "slack", "priority": "2"}. Filters compare values as text. - Attachments are stored as BLOBs in the database, up to 25 MiB each. The type is
detected from the file's bytes, never from its name. Images display inline; everything
else downloads, with
nosniffset, so an uploaded HTML file cannot run on this origin. - Filenames are searchable, so
cairn search packingfindspacking-list.txt.
Access tokens
- Format:
cairnt_followed by 64 hex characters. - Stored as a SHA-256 hash, with the last four characters kept for display.
- Scopes:
read(list, search, get, download) andwrite(create, edit, delete, tag, upload).writeimpliesread.--read-onlycreates aread-only token. - Send as
Authorization: Bearer <token>. - Revoking a token takes effect on the next request.
Accounts and sessions
- Sign-in is a username and password. Passwords are hashed with argon2. Usernames are case-insensitive; user-chosen passwords are at least 12 characters.
- Signing in creates a server-side session. The browser holds a random
cairns_secret in anHttpOnly,SameSite=Strictcookie, and the server stores only its hash. Sessions last 30 days, and signing out deletes the session. - A signed-in person has full access to the archive. Tokens are how scripts and agents get in, and the Tokens page lists and revokes them.
- All accounts share one archive. There is no per-user ownership of items.
CLI
export CAIRN_TOKEN=cairnt_…
cairn add --title "Lifetimes" --tag rust "Lifetimes tie references to scopes."
cairn add --tag travel --meta source=camera --file beach.png # a picture
some-command | cairn add --tag logs # text from stdin
cairn ls --tag rust --sort created --order asc --limit 20
cairn ls --meta source=camera # metadata filter
cairn search borrow checker # all words must match; prefixes too
cairn get <id> # shows metadata and files
cairn edit <id> --title "New title"
cairn edit <id> --content-file notes.md # or `-` for stdin
cairn edit <id> --meta source=phone --meta place=lisbon # replaces all metadata
cairn tag <id> reference web
cairn untag <id> web
cairn attach <id> photo.jpg other.pdf
cairn fetch <file-id> --out photo.jpg # or no --out to pipe to stdout
cairn detach <file-id>
cairn rm <id> # also deletes its files
cairn tags
cairn whoami
cairn add prints only the new id, so it works in scripts:
id=$(cairn add --tag todo "buy batteries").
HTTP API
Base path /api/v1. JSON in and out, except uploads and downloads, which use raw bytes.
Errors are {"error": "..."}.
| Method | Path | Scope | Notes |
|---|---|---|---|
GET | /me | any | The token in use |
GET | /items | read | q, tag, meta.<key>, sort, order, limit, offset |
POST | /items | write | {"title"?, "content"?, "tags"?, "metadata"?} → 201 |
GET | /items/{id} | read | Includes metadata and attachments |
PATCH | /items/{id} | write | {"title"?, "content"?, "metadata"?}; metadata replaces the whole object |
DELETE | /items/{id} | write | 204; also deletes its attachments |
POST | /items/{id}/tags | write | {"tags": [...]} adds tags |
DELETE | /items/{id}/tags/{tag} | write | Removes one tag |
POST | /items/{id}/attachments?filename=… | write | Raw file bytes as the body → 201 |
GET | /attachments/{id} | read | The file's bytes |
DELETE | /attachments/{id} | write | 204 |
GET | /tags | read | Tags with counts |
GET | /tokens | write | Token metadata; never secrets |
qis full-text search over title, content, tags, and filenames. Each word is matched as a prefix and all words must match. Withoutsort, results are ranked by relevance whenqis given and by last update otherwise.meta.<key>=valuefilters on a top-level metadata key. Repeat it to require several.sortisrelevance,created,updated, ortitle.orderisascordesc.- Tags are lowercased,
#is dropped, inner spaces become-, and only letters, digits,-,_, and.are allowed (up to 64 characters). - A new item needs text or a title. If
titleis omitted, it comes from the first non-empty line of content. - Text content is limited to 10 MiB and each file to 25 MiB.
# create an item
curl -s -X POST http://127.0.0.1:8080/api/v1/items \
-H "Authorization: Bearer $CAIRN_TOKEN" -H 'Content-Type: application/json' \
-d '{"content":"remember this","tags":["agent"],"metadata":{"source":"agent"}}'
# attach a picture to it (the id comes from the response above)
curl -s -X POST "http://127.0.0.1:8080/api/v1/items/$ID/attachments?filename=beach.png" \
-H "Authorization: Bearer $CAIRN_TOKEN" --data-binary @beach.png
# search
curl -s "http://127.0.0.1:8080/api/v1/items?q=remember&meta.source=agent" \
-H "Authorization: Bearer $CAIRN_TOKEN"
Web
/— paste box with title, text, files, tags, and metadata, plus recent items/search?q=…&tag=…— search results/items/{id}— view, edit, tag, attach files, or delete an item/attachments/{id}— a file, shown inline if it is an image
The Tokens page creates and revokes API tokens. The Account page changes your password.
Deploying
Run behind a reverse proxy that terminates TLS, and bind the app to loopback
(BIND_ADDRESS=127.0.0.1). Keep DB_PATH on persistent storage. The session cookie
does not set Secure, so it should only ever travel over HTTPS.
Create the first account inside the running container. The password is printed once:
ino once exec cairn.silenlocatelli.ch cairn user create silen
Sign in at the app with that password, then create API tokens on the Tokens page.
Development
mise run test # cargo test
mise run verify # fmt check, clippy (pedantic), tests