Settings reference

Settings open from the gear button at the top of the sidebar, or from the Open Settings command in the command palette (Cmd/Ctrl+Shift+P). Clicking the dimmed area outside the panel closes it too.

Escape also closes it, with one exception. The global Escape handler runs a strict cascade, and the command palette comes first. If the palette is open on top of Settings, the first Escape closes the palette and the second closes Settings.

There is no Save button. Every control writes through immediately, so the footer buttons labeled Close and Done do exactly the same thing, and a stray click outside loses nothing. The panel is a single scrollable column of section cards rather than a set of tabs.

How the screen is organized

Section	What it covers
Appearance	Theme, fonts, and visual preferences.
Editor	How notes open and behave inside the editor.
Daily Notes	Calendar and task timing for the right sidebar.
Semantic search	Search by meaning alongside keyword search. The model and index stay on this device.
Account & sync	End to end encrypted cloud sync. Notes are encrypted on this device before upload.
Agents	Keeps agent instruction files, skills, and subagent definitions in sync between the vault’s Agents/ folder and this machine’s config directories.
Advanced	Defaults, maintenance, and diagnostics you will not need often.
About	The app logo, the installed version number, and the tagline.

Six sub groups start collapsed. Open one to reach the rows inside it.

Sub group	Lives inside
Templates	Editor
Security & recovery	Account & sync
Files & folders	Advanced
Document conversion	Advanced
Diagnostics	Advanced
Command-line tool	Advanced

Rows in this panel have three parts: a label on the left, a helper line under it, and a control on the right. The label and the button text often differ, so this page names both wherever they do.

Appearance

Setting	Effect	Default
Theme	Match the operating system or pick a fixed mode. Options are System, Light, and Dark.	System
Editor font family	The typeface used for the editor surface. The list is populated from the fonts installed on your machine, and the first option is literally (default monospace).	ui-monospace, SF Mono, Menlo, Consolas, monospace
Editor font size	Text size in the editor, between 10 and 24 pixels.	15
Sidebar font size	Text size in the file tree and the search pane, between 10 and 20 pixels.	14

All four apply live, with no restart. When Theme is set to System, the app watches the operating system’s light and dark preference and follows it as it changes.

Editor

Setting	Effect	Default
Open in source mode	Show raw Markdown by default instead of the formatted view. You can still toggle either way per note with Cmd/Ctrl+Shift+E.	false
Load remote images	Allow images hosted on the web to load inside notes. This is off by default for privacy, because loading a web image reveals your IP address and your reading activity to whoever hosts it.	false

See The editor for what source mode changes and Keyboard shortcuts for the full chord list.

Templates

The Templates sub group is not a stored setting. It is a manager for template files, which live in your vault at .jotura/templates/<name>.md. A template body may use the variables {{date}}, {{datetime}}, {{filename}}, and {{title}}.

It needs a vault. With no vault open the group shows a single row reading Open a vault to manage templates. and no editor. With a vault open but no templates yet, it shows a No templates yet row and a New template… button.

Nested names such as work/standup are allowed. Renaming a template is not supported, so the name field is read only when you edit an existing one. Deleting asks you to confirm, and notes already created from that template are not affected.

The CLI reads and writes the same files:

jotura templates list --json

More on templates in Daily notes, tasks, and templates.

Daily Notes

Setting	Effect	Default
Enable daily notes	Show the calendar in the right sidebar and pre-create notes for upcoming days. Turning this off hides the two settings below.	true
Auto-create window	How many upcoming days are pre-created when the app starts, from 1 to 60.	14
Task window	How far back to look for tasks in recently modified notes and recent daily notes, from 1 to 365 days. Tasks dated in the future always appear regardless of this value.	30

One limitation worth knowing before you commit to daily notes: there is no setting anywhere for the daily notes folder. It is always Daily.

Clicking any cell in the calendar creates that day’s note, including the grayed-out cells that belong to the previous or next month.

Semantic search

Semantic search finds notes related to your query even when the words differ. Its state does not live in the settings file. It is backed by the vault’s own index and by model files on disk, and the settings screen polls that state every two seconds while it is open.

When it is off, the section shows one row labeled Search by meaning with an Enable button. Enabling downloads the bge-small-en-v1.5-int8 embedding model, version v1, which is roughly 34 MB in two files, model.onnx and tokenizer.json.

Both files come from this base URL, and each is verified against a SHA-256 checksum:

https://releases.jotura.io/models/bge-small-en-v1.5-int8/v1/

They are stored at <config dir>/jotura/models/bge-small-en-v1.5-int8/v1/, where <config dir> is the same directory that holds settings.json (see Where settings are stored). While the download runs, the helper line reads Downloading the embedding model… <pct>% and the Enable button is replaced by that percentage. The app then builds the index in the background.

Once it is on, the section shows three rows and offers two actions.

Row label	Button	What it shows or does
Status	none	The model version, with the compute backend as its value: one of GPU (CUDA), GPU (DirectML), GPU (CoreML), CPU, or Unknown.
Index	none	The number of indexed chunks and the number still pending, plus an estimated time remaining while embedding is running.
Re-index vault	Re-index vault	Clears the existing chunks and rebuilds them in the background.
Turn off semantic search	Turn off & delete index	Disables semantic search and deletes the local index. Your notes are untouched, and re-enabling rebuilds the index from scratch. This action asks you to confirm.

If enabling or indexing fails, a Last error row appears carrying the message, with the value Failed. The same pattern is used by the document conversion, sync, and command-line tool groups.

Nothing is sent anywhere beyond that one model download. The model runs on your machine and the index stays in the vault.

The CLI can query this index but never builds it, so notes written from the CLI are not findable by meaning until the desktop app indexes them. Running a semantic query with no index exits with code 13:

jotura search --mode semantic "onboarding decisions" --json

See Search and Reading and searching.

Account & sync

Sync is optional, and it requires a paid subscription. Pricing is on the pricing page.

When you are signed out, the section shows one row: label Status, helper Sign in to enable cross-device sync., and a Sign in button. Signing in asks for your email address and then a six digit code, which expires in 15 minutes. A Resend code button is limited to one send every 30 seconds.

When you are signed in, the section adds up to three account rows above the sync status.

Row label	Button	What it does
Signed in as	Sign out	The helper line is your email address. Signing out asks you to confirm first.
Plan	Manage billing	Shown only while you have a subscription. The helper names the plan and its renewal, trial end, or cancellation date. The button opens https://jotura.io/account in your browser.
Restore vault from cloud	Restore from cloud	Picks a vault from your account and downloads it into a local folder you choose.

The sync status below those rows depends on where the current vault stands. The first matching case wins.

Situation	What you see
No vault open	A Status row reading Open a vault to enable sync.
Signed in with no subscription	An upgrade card explaining what sync adds.
Sync not configured on this vault	A row labeled Enable sync with an Enable sync… button that sets a sync password and issues a recovery phrase.
Sync key not cached on this device	A row labeled Sync password needed with an Unlock sync… button. Its helper reads Sync is paused until you enter your sync password. Notes stay fully usable meanwhile.
Sync configured and running	A Status row plus an Actions row carrying Pause sync or Resume sync.

In the running case the Status row’s helper is one of these ten sentences.

Status helper	Meaning
Idle. All changes pushed.	Everything local is on the server.
Registering vault on the server…	First time setup for this vault is in progress.
Syncing <n> of <n> notes… or Syncing…	An upload pass is running.
Pulling <n> of <n> notes…	A download pass is running.
Error: <message>	The last pass failed. The message is shown verbatim.
Offline. Will retry when online.	The app has no network connection.
Not registered.	The vault has never been registered with the server.
Not signed in.	No account session on this device.
Sync key needed. Unlock sync with your password.	The key is not cached here.
Paused. Server copy preserved. Resume to push pending edits.	You paused sync. Edits queue locally.

When sync reports an error, an extra row appears. It is labeled Last error, its helper carries the message, and its button reads Retry, which starts a fresh push. That row also appears for a transient failure from an action you just triggered. In the error state the Actions row is hidden, so Retry is the only sync control on screen.

Sync never blocks local work. Reading, writing, and search all keep working when sync is paused, offline, or missing its key.

Security & recovery

Row label	Button	What it does
Change sync password	Change sync password…	Opens three more rows: New sync password, Confirm new password, and Save. The minimum is 12 characters. The master key is re-wrapped on your device first, and only the wrapped result and the key derivation parameters go to the server.
New recovery phrase	New recovery phrase…	Generates a fresh phrase and invalidates the old one. It asks for your current sync password first, and the phrase is shown once during the ceremony. The server side is updated before the local commit.
Forget key on this device	Forget key	Clears the cached sync key and deletes the session file. Sync moves to the paused, password needed state until you enter your sync password or your recovery phrase again. Your notes stay fully usable on this device. This action asks you to confirm.

The recovery ceremony shows 12 numbered words. It offers a Copy to clipboard button that copies them numbered and one per line, then asks you to type back three of them chosen at random.

More context in Sync and sharing and Sync and shares.

Agents

This section manages the reconciler described in full in The agent surface, from inside the app. It needs an open vault. With none open it does not appear at all.

Two rows sit at the top of the section, always visible.

Row label	Control	What it does
Auto-sync	toggle	Applies changes from the vault’s Agents/ folder to this machine automatically. Default on, stored as agentsAutoSync in settings.json.
Sync now	Sync now button	Runs a sync immediately and refreshes the rows below with the result.

Below those, drift is listed by item. Items that already match collapse into one row labeled In sync, reading <n> item in sync or <n> items in sync, helper No action needed. Everything else gets its own row, one of Apply to this machine, Pull into the vault, Adopted into the vault, Conflict, No longer in the vault, or Missing on this machine for a runtime that is not installed here. Each row names the item key as agents status prints it, for example claude/CLAUDE.md.

A Conflict row is the only one with buttons of its own.

Button	Effect
Keep vault	Syncs only that item, taking the vault’s copy. Equivalent to jotura agents sync --item <key> --prefer vault.
Keep this machine	Syncs only that item, taking this machine’s copy. Equivalent to jotura agents sync --item <key> --prefer system.

Resolving a conflict this way touches only the item you picked. Every other pending item is left for the next Sync now click or the next auto-sync run.

After any run, whether triggered by the toggle, the Sync now button, or a conflict resolution, any warnings the run reported, such as a skipped binary file, are listed first, followed by a Last sync row that summarizes it: Applied N, pulled N, conflicts N, pruned N.

If the bundled jotura CLI is not on this device, the whole section collapses to a single row, Agent sync unavailable, because the reconciler runs through that binary under the hood. Reinstalling Jotura restores it.

Auto-sync semantics

Auto-sync runs once when you open the vault, and again whenever a file inside the vault’s Agents/ folder changes on disk, whether the change came from you editing it, another machine’s sync pulling it in, or a hand edit outside the app. Rapid changes are coalesced: the app waits for 2 seconds of quiet after the last change before it runs, so editing several files in a row triggers one run rather than one per file.

Auto-sync never resolves a conflict on its own. If a file changed on both sides since the last sync, an automatic run reports the conflict and leaves it exactly as Sync now would, for you to resolve with Keep vault or Keep this machine. A failed auto-sync run is logged and otherwise silent: it never shows an error dialog and never blocks editing.

Cross-machine flow

The vault’s Agents/ folder is ordinary vault content, so it travels between your machines through Jotura’s normal end to end encrypted cloud sync, the same as any note. Edit Agents/Claude/CLAUDE.md on one machine, and once cloud sync carries the change across, the other machine picks it up: the desktop app applies it automatically through auto-sync, or you can run jotura agents sync from the CLI yourself. Both surfaces read and write the same files, so it makes no difference which one you used to make the change or which one applies it.

See The agent surface for the three-way reconciliation model, the full registry of runtimes, and every CLI flag, including --item for syncing a single item at a time, which is what the conflict buttons above use.

Advanced: Files & folders

These are the default locations for new notes and imported documents.

Setting	Effect	Default
Default new-note directory	Where new notes are created, relative to the vault root. Leave it blank to use the root itself.	Blank, meaning the vault root
Default document folder	Where documents you drop or paste into the app are stored, relative to the vault root.	attachments
Confirm before deleting	Show a confirmation dialog before moving a note to the trash.	true

Deleting from the app is one way. A deleted note moves into <vault>/.jotura/trash/ rather than the operating system trash, and there is no trash browser in the desktop app. Listing, restoring, and permanently purging a trashed note are CLI-only:

jotura trash list --json

That side is covered in Creating, moving, and deleting.

Advanced: Document conversion

Imported documents such as PDFs, Word files, and spreadsheets are converted to searchable Markdown by a converter bundled with the app. The group header shows an Unavailable badge when that converter is missing, and an <n> failed badge when conversions have failed. With zero failures, which is the normal state, there is no badge at all.

The first row reports the converter itself.

Row label	When it shows	What it says
Converter	The converter is present.	Its value reads Ready.
Conversion unavailable	The converter is missing.	Documents still import, but stay un-searchable until the converter is present. Reinstalling Jotura restores it.

That second row is the one to look for when an imported document never becomes searchable.

One real setting sits below it, and it is always visible.

Setting	Effect	Default
Allow unsandboxed conversion	Convert documents without operating system sandboxing on machines where no sandbox is available. Off by default, which means conversion is skipped rather than parsing an untrusted file with your full account privileges. Only turn it on if you trust every document you import.	false

Everything else in the group is conditional. The status row and the five action rows appear only when the converter is present, a vault is open, and that vault has at least one imported document. In a vault with no documents you get a No documents in this vault row instead, reading Conversion options appear once a document is imported.

Row label	Button	What it does
Conversion status	none	Reads <n> converted · <n> failed · <n> pending for the open vault.
Reconvert stale documents	Reconvert stale	Re-runs conversion for documents whose source changed or whose conversion is out of date.
Reconvert all documents	Reconvert all	Re-runs conversion for every document in the vault. This is heavy on a large vault.
Convert pending documents	Convert pending	Runs the background sweep now for anything missing a searchable copy.
Retry failed conversions	Retry failed conversions	Re-runs the failed documents, bypassing the automatic backoff. Failures are usually corrupt or password protected files.

The last row is nested inside a disclosure that appears only when something has failed. Its toggle reads Show <n> failed…, expands to the list of failed paths, and then reads Hide failed. While a reconversion runs, a Progress row counts documents converted, and when one finishes a Result row reports the outcome.

See Documents for how importing works.

Advanced: Diagnostics

Everything in this group stays on your machine. It has two halves: sync diagnostics at the top, then the support report and the log path.

Sync diagnostics

These rows appear only when three things are true at once. You are signed in, a vault is open, and sync is configured on that vault. Signing in with a vault that has never had sync enabled shows none of them.

While the first reading is in flight you see a single Loading row reading Fetching sync state…. After that, the rows refresh every two seconds.

Row label	What it shows
Account	The email this device is signed in with.
Device ID	The identifier of this install. Both devices must be signed in to the same account.
Vault ID	The server vault this device points at. Two devices must show the same ID for changes to sync.
Pending ops	Local changes queued for the next push. This should drop to zero shortly after you edit.
Server version	The last manifest version this device pulled.
Last push	How long ago the last push ran, with the number of operations in the helper.
Last pull	How long ago the last pull ran, with the number of operations applied.
Last push error	Shown only when a push has failed. The message is in the helper.
Last pull error	Shown only when a pull has failed.
Re-pull from server	The button reads Force re-sync. It resets the local cursor and re-fetches the entire manifest from the server, keeping your local pending edits. It asks you to confirm first, then reports what it applied in a Result row.

Use Force re-sync when changes from another device are not appearing. Version history covers what the server keeps per note.

Support report and log

Row label	Button	What it does
Diagnostics	Copy diagnostics	Builds a support report and copies it to your clipboard. The button briefly reads Copied, or Copy failed if the clipboard write did not work.
Log file	none	Shows the full path to the app’s log file, or (unavailable) if there is no resolvable path.

Read the report before you paste it anywhere public. It opens with the app version, your operating system, and your architecture. It then records whether a vault is open, whether sync is enabled, whether the sync key is loaded, and the vault’s name. It ends with the converter’s availability and version, the sandbox kind in use, the conversion counts, and the last 200 lines of the log.

It contains no filesystem paths, no note contents, and no keys. Nothing is sent anywhere, so you paste it into a bug report yourself.

The CLI has a broader health check that covers the same ground and more:

jotura doctor --json

Both are described in Troubleshooting and Watching and diagnostics.

Advanced: Command-line tool

Every desktop installer ships the jotura command line tool alongside the app. This group puts it on your PATH, and it appears on macOS, on Windows, and in the Linux AppImage build. It is absent in the Linux .deb build, where the tool already lands on the standard PATH.

The group has two rows. Status reports where the tool currently is, and the action row’s button reads Install or Reinstall depending on that status.

Status	Meaning
Not installed	The tool is not on your PATH yet.
Installed (<path> is on PATH)	Windows only. The install directory is on your user PATH.
Installed at <path>	The link or copy points at the binary bundled with this app.
Installed at <path> (points elsewhere; reinstall to update)	Something else is answering to jotura, such as a separate build. Reinstall to point it at this app’s binary.
Unable to detect	The app could not read the install state.

What the action does depends on your platform.

Platform	What happens	How to remove it later
macOS	Creates a symlink at /usr/local/bin/jotura. This needs administrator rights, so macOS prompts you for your password.	sudo rm /usr/local/bin/jotura
Windows	Adds Jotura’s install directory to your user PATH. New terminals pick it up automatically. If it fails, a Last error row reports Could not update PATH.	Edit PATH under System Properties, Environment Variables.
Linux AppImage	Copies the binary to ~/.local/bin/jotura. Make sure that directory is on your PATH.	rm ~/.local/bin/jotura

On Windows and on the Linux AppImage, the app also offers to do this once at startup, but only when the tool is not already installed. That prompt records that it has been shown whether you accept or decline, so it never asks a second time and it cannot be reset from Settings. Use this Settings group if you dismissed it and later changed your mind. On macOS this group is the only offer.

Full setup notes are in Install and setup.

About

The About section shows the Jotura logo and wordmark, the installed version number, and the tagline Local-first markdown notes. There are no controls in it.

Where settings are stored

Settings are a single JSON file in your operating system’s configuration directory.

Platform	Path
Windows	%APPDATA%\jotura\settings.json
macOS	~/Library/Application Support/jotura/settings.json
Linux	~/.config/jotura/settings.json

If no configuration directory resolves at all, the app falls back to ./jotura/settings.json, relative to the process working directory. That is rare, and it is worth checking if your settings appear to live nowhere.

Three more things about that file are worth knowing.

The file is written in place, without a temporary file and rename, and it is not flushed to disk explicitly. If the app is killed part way through a write, the file can be left truncated. On the next start an unparseable settings file is silently replaced by the defaults, so the symptom of that failure is your preferences resetting rather than an error message.

Field names are camelCase and each missing field falls back to its own default, so a settings file written by an older version still loads. There is one migration in place: a stored API address pointing at the retired staging server is rewritten to https://api.jotura.io on load. The JOTURA_API_URL environment variable overrides the address for a single run and is never written back to the file.

The frontend applies your change optimistically and does not surface a failure from the backend write. If a change does not survive a restart, check that the settings file is writable.

Preferences stored outside settings.json

Some preferences live in the app’s own browser storage instead. They are per device and are not synced.

Preference	How you set it	Range and default
Sidebar width	Drag the divider between the sidebar and the editor. The handle is also keyboard reachable: Tab to it, then ArrowLeft and ArrowRight resize in 16 pixel steps, saved immediately.	200 to 600 pixels, default 300
Right sidebar width	Drag the divider on the right side. This one is mouse only, with no keyboard equivalent.	No fixed range documented
Right sidebar collapsed	Toggle the right sidebar.	Collapsed by default
Recently closed tabs	Built automatically as you close tabs.	20 entries per vault
Show autosaves in history	The Autosaves filter chip in the version history tab.	Off until you turn it on
History diff layout	The Unified and Split toggle in version history, covered in Version history.	Unified

What the CLI shares

The jotura CLI reads some of the same state, which is why the two surfaces agree without any extra configuration.

Shared state	How the CLI uses it
Last opened vault	When you do not pass --vault and JOTURA_VAULT is unset, the CLI resolves the vault from the desktop app’s lastVaultPath in settings.json.
Sync key cache	Both surfaces cache the per vault sync key in the same session directory under your configuration directory. Signing in to sync from either one resumes it for the other.
Templates	Both read and write .jotura/templates/ in the vault.
Semantic index	The CLI queries the index the desktop app builds. It never indexes.
App version	jotura doctor reports the desktop app version it finds in settings.json.

The CLI has environment variables of its own, including overrides for the session directory and the model directory, and those are covered in Install and setup. Its exit codes and JSON conventions are in Exit codes and JSON output.