Notebooks as Git

A notebook is a Git repository of Markdown files. You can clone it, work in your own editor, and push back — and if you stopped using Kyra tomorrow you would keep the notes and the history.

There are two ways in. Use the CLI if you just want the files; use SSH if you want to treat it like any other repository.

The quick way: the CLI

kyra pull --vault notes                              # into ~/.kyra/vaults/notes
kyra push --vault notes -m "notes from the drive"    # write edits back

No SSH key to set up — each run mints a temporary key and discards it.

The first pull asks you to approve read-only note access in the portal.
push asks for its own, separate approval. Write is a higher-trust grant than read, and bundling the two would mean approving one to get the other.
--out <dir> puts the clone somewhere else.
A dirty tree is refused unless you pass -m, which stages and commits everything first. Otherwise commit with git yourself and kyra push only does the network write.

Full options →

Keeping a clone fresh automatically

kyra connect --watch notes,work

Refreshes those notebooks whenever a note changes, so a notebook you dictated into from the car is already on disk by the time you sit down. Bare --watch does every cloned notebook.

The full way: clone over SSH

Treat the notebook as an ordinary Git remote.

Add your public key in Portal → Settings → SSH keys.
Open Clone in the notebook toolbar and copy the URL.
Clone it:

git clone ssh://git@<host>:<port>/<username>/<notebook>.git

From there everything is normal Git: branches, log, diff, rebase, worktrees, your usual tooling. Push and the change appears in the portal, in the app, and to Kyra.

Right when you want your own directory layout, your own commit discipline, or the notebook alongside your other repositories.

Working in your editor

Once cloned, the notes are just files.

VS Code — a folder of Markdown. Add a Markdown extension you like and it is a perfectly good notes environment, with your usual search and multi-cursor editing.

Obsidian — point a vault at the clone. Wiki-links work the same way in both directions, so [[research/interviews/sarah]] written in Obsidian is a working link in Kyra and vice versa.

Anything else — it is Markdown in a Git repository. Use whatever you use.

Things worth knowing

Kyra keeps writing. If you leave a clone alone for a week while dictating notes, you are behind. git pull (or kyra pull) before you start.

Conflicts are ordinary Git conflicts. Edit the same lines in both places and you resolve it the usual way. Frequent small pulls avoid it, as always.

Some things are not in the repository. Tags, links, and the search index are derived from the notes and rebuilt by Kyra — they are not files you edit. Sharing settings and publishing configuration live with the notebook, and publishing configuration is a file (kyra.toml), so that one you can edit either way.

Renaming is safe. Notes carry a stable identifier, so moving or renaming a file does not break the links to it.

Local browser notebooks cannot be cloned. They only exist in that browser. Make a cloud notebook if you want it anywhere else.

Automating with it

Cloning is also the supported way to build something on top of your notes: a scheduled kyra pull, then your own script over a directory of Markdown. No API to learn, no rate limit, and it keeps working when Kyra is down.

Writing back means committing and pushing, exactly as anything else would.