Advanced

The sempere command line

Common tasks with real commands: setting up, reading and searching, exporting, backups, recognition, verification and scripting.

The sempere CLI runs on macOS and Linux and works on the same vault folders as the app. This page covers the tasks most people need. Every command and flag is in the full reference, docs/cli.md, and sempere help <command>.

To install it, see Install.

Tell it which vault and key

Every command needs the vault: --vault PATH or the SEMPERE_VAULT variable. Commands that read notes also need a key, found in this order:

--recovery-key FILE: the recovery key (a file with the kit’s key, or the vault’s passphrase copy keys/recovery-*.key.age). It opens the vault read-only. Add --root with the kit’s 16 groups to check the vault against the kit;
--identity FILE or SEMPERE_IDENTITY: a device key file;
this machine’s own device key for the vault, made by vault init or device init and kept in ~/.local/state/sempere/devices/ (mode 600). A passphrase-locked one takes its passphrase from --passphrase-env VAR, SEMPERE_PASSPHRASE, or a prompt.

To write, a machine must be one of the vault’s devices: it created the vault, or it joined it (see Keys and devices below). A passphrase never goes on the command line.

export SEMPERE_VAULT=~/Notes.sempere
sempere vault info

A note is named by its title, its id, or an id prefix of four or more characters.

Read and search

sempere notes list --sort modified
sempere notes list --notebook School --tag exam
sempere notes show "Week 3"
sempere notes search eigenvalue                  # titles, text, recognized handwriting
sempere search "Fourier" --transcripts           # every occurrence, with recordings
sempere notebooks list
sempere tags list

Write and organize

sempere notes new "Week 4" --notebook School/Physics --tag physics --paper grid
sempere notes tag "Week 4" --add exam --remove draft
sempere notes move "Week 4" School/Exams
sempere notes rename "Week 4" "Week 4: Optics"
sempere notes favorite "Week 4"
sempere notes delete "Old list"                  # to Recently Deleted; undelete brings it back

The CLI has no drawing command; ink comes from the app.

Export

sempere export "Week 3" --format pdf --out week3.pdf
sempere export "Week 3" --format png --dpi 300 --out week3-png
sempere export --all --format markdown --images png --out ~/Obsidian/Sempere
sempere export --all --format html --out ~/notes-html
sempere export --all --format pdf --layout notebooks --zip --out notes.zip

Formats: pdf, svg, png, markdown, html, json, media. Exports are not encrypted. Running a bulk export again skips unchanged notes.

Back up and restore

A backup copies only the encrypted files that are new, so it needs no key:

sempere backup "$SEMPERE_VAULT" --to /Volumes/Backup/Notes.sempere-backup -q
sempere backup verify /Volumes/Backup/Notes.sempere-backup                     # structure and hashes, no key
sempere backup verify /Volumes/Backup/Notes.sempere-backup --recovery-key key.txt  # also decrypts everything
sempere backup status /Volumes/Backup/Notes.sempere-backup --max-age 7         # exit 3 if older than 7 days
sempere backup "$SEMPERE_VAULT" --archive notes-backup.tar      # one tar file
sempere restore /Volumes/Backup/Notes.sempere-backup --to ~/Restored.sempere

A backup is a snapshot for recovery; nothing syncs from it. It keeps revisions that the vault later thins away (unless you run it with --prune), and older versions of replaced files such as vault.json in its versions/ folder. See Nightly encrypted backup with the CLI and cron.

Check a vault

sempere vault verify          # exit 0 healthy, 3 problems found, 6 device list does not check
sempere blobs verify          # attachments

Recognize handwriting and transcribe (macOS)

sempere recognize --all --missing-only    # read every note not read yet
sempere recognize --recent --days 7
sempere transcribe --all                  # transcribe recordings

On Linux these commands report an error and change nothing.

Import

sempere import notability ~/Downloads/Notability-backup.zip --dry-run
sempere import pdf paper.pdf --title "Paper" --notebook Reading --tag research

Keys and devices

sempere vault init ~/Notes.sempere --recovery-out recovery.txt --name "laptop"   # this machine is home
sempere keys paper --identity recovery.txt --vault ~/Notes.sempere --out kit.pdf  # print, then delete both
sempere device init --name "linux box"                  # join from another machine: prints six words
sempere devices approve WORD WORD WORD WORD WORD WORD   # on the home device
sempere device confirm WORD WORD WORD WORD WORD WORD    # back on the new machine
sempere devices list
sempere devices remove ID

Device keys never leave their machine; no command exports one. See Managing devices and keys.

Sync

export SEMPERE_WEBDAV_PASSWORD='…'
sempere sync webdav https://nas.example.org/dav/notes.sempere/ --user me     # two-way
sempere sync folder /mnt/usb/notes.sempere                                     # two-way
sempere webdav check https://nas.example.org/dav/ --user me                    # test, list vaults
sempere store sync Notes                                                       # a store vault's targets

See WebDAV and NAS setups.

Scripting

--json gives machine-readable output on nearly every command (times in UTC); -q keeps quiet on success.
Errors go to standard error, one line each, starting with sempere:.
Exit codes: 0 success, 1 failure, 2 usage error, 3 problems found (verify, overdue backup, sync conflicts), 4 cannot decrypt (no key, or this machine has not joined), 6 the device list does not check, 7 read-only (a vault from a newer version, or opened with the recovery key), 8 this machine was removed from the vault.

sempere notes list --json | jq -r '.[] | .id + "  " + .title'
sempere vault verify -q --json | jq .healthy