Sync and sharing

Sync is optional. A vault works fully offline with no account, and everything on the Getting started page happens before sync enters the picture. When you turn sync on, your notes are encrypted on your own device before anything is uploaded, and the same vault appears on your other machines.

Sharing is built on the same machinery. You can share a whole folder or a single file with another Jotura user, as an editor or a viewer, without moving anything out of your vault.

Sync and sharing both require a paid Jotura Sync subscription, which is £4 a month or £40 a year with checkout in your local currency where supported, and the details are on the pricing page.

Turning sync on

There are three separate steps, and they are genuinely separate. Signing in gives you an account. A subscription gives that account sync entitlement. Enabling sync creates the encryption keys for one particular vault.

1. Sign in

Open Settings, expand Account & sync, and click Sign in. Signing in is passwordless and uses a one-time code rather than a link.

Step	What happens
Enter email	The dialog says “We’ll email you a 6-digit code to sign in. No password needed.”
Enter code	A 6-digit numeric code arrives by email. The dialog notes “It expires in 15 minutes.”
Resend	The Resend code link is disabled for 30 seconds after each send.

Jotura also registers a jotura://auth deep link. Opening a link of the form jotura://auth?email=…&code=… prefills both fields and jumps straight to the code step.

While you are signed out, the Settings row reads “Sign in to enable cross-device sync.” Once you are signed in it reads “Signed in as <email>”, with a Sign out button that confirms first: “Sign out of <email>? You can sign back in any time.”

2. Subscribe

If your account has no active subscription, the app shows a subscription card wherever sync or sharing would start. The card pitches “Sync your vaults across devices, end-to-end encrypted.” and gives the price as “£4/month or £40/year (billed in your local currency where supported).” It offers two buttons: Get Jotura Sync, which opens the pricing page in your browser, and Already subscribed? Refresh, which re-checks your entitlement without restarting the app.

When you are subscribed, a Plan row appears in Settings with a Manage billing button that opens https://jotura.io/account.

3. Enable sync for the vault

With a vault open and an entitled account, the Settings row reads “Enable sync. Set a sync password and get a recovery phrase. Notes are encrypted on-device before upload; the server never sees your notes or the password.” Clicking it opens a wizard.

Step	Title	What it asks for
Intro	Set up encrypted sync	Nothing. It explains the encryption and warns that “Losing both the password and the phrase means losing access to synced data on new devices.”
Password	Choose a sync password	The sync password, twice. Minimum 12 characters. The hint reads “At least 12 characters.”, and adds “Password is too short.” or “Passwords don’t match.” as needed.
Enabling	Enabling sync…	Nothing. “Creating your sync keys and registering this vault.” This step cannot be closed.
Phrase	Save your recovery phrase, then Confirm recovery phrase	Your attention, then three words back. This is one wizard step with two stages.
Done	Sync is on	Nothing. “Sync is enabled. Your notes are uploading end-to-end encrypted in the background.”

There is a sixth step you only see when something is wrong. If enabling fails because the account has no entitlement, the wizard switches to a step titled “Jotura Sync subscription needed”, reading “Your account doesn’t have an active Jotura Sync subscription yet. Subscribe on the website, then come back and enable sync.” The subscription card is embedded below it.

Your sync password is not your account password. Your account has no password at all. The sync password exists only to protect the vault’s encryption key, and the server never receives it.

If you try to close the wizard while the phrase is on screen, it asks first: “Sync is already enabled, but you haven’t confirmed your recovery phrase. It will NOT be shown again. Without it and your password, synced data is unrecoverable on new devices. Close anyway?”

What end-to-end encryption means here

Encryption applies to data in transit and to data stored on the server. On your own disk, notes stay plain markdown files with no wrapper of any kind, exactly as they were before you enabled sync. At-rest protection on your own machine is your operating system’s job, through FileVault or BitLocker.

The server holds	The server never holds
Your account email	Note content in plaintext
Opaque encrypted blobs	Plaintext paths or filenames
HMAC’d path identifiers, used to route updates without learning the filename	Your sync password, or any key derived from it directly
The key-derivation salt and parameters	Your master key in a form it can unwrap
A verifier blob proving you can derive the key
Your master key wrapped under a key it cannot derive, plus a second copy wrapped under your recovery phrase

That last row is the one people get wrong. Wrapped copies of the master key do sit on the server, because that is what lets a new device sign in and decrypt the vault. The server cannot unwrap either copy: one needs your sync password, and the other needs your recovery phrase, and it holds neither.

The parts of the scheme worth knowing:

Piece	What it is
Key derivation	Argon2id over your sync password, with m=64 MiB, t=3, p=4. The output is a key-encryption key.
Master key	32 random bytes generated when you enable sync, wrapped under the key-encryption key. It is not derived from your password, which is why changing the password is cheap.
Per-file keys	Every upload gets its own data encryption key, wrapped under the master key. Content is encrypted with XChaCha20-Poly1305 on your device at push time.
Filename privacy	The server-visible identifier is HMAC-SHA256(path_key, normalized_path). It is deterministic enough to route updates and opaque to the server. The real filename is encrypted alongside the wrapped key.

Changing your sync password re-wraps the master key locally and then updates the salt, parameters, and wrapped key on the server. Your notes are not re-encrypted, because the master key itself has not changed. More background sits on the security page.

One caveat belongs here rather than anywhere else. Your device key and your account identity key, which is what shares are sealed to, are stored in plaintext in settings.json under your user config directory. They are protected by the file permissions of your user profile and nothing more. The vault’s master key is not kept there, but treat that file as sensitive. The Settings reference lists where it lives on each platform.

The recovery phrase

The phrase is 12 BIP39 words, generated when you enable sync and shown once. The phrase itself is never sent to the server. What the server stores is a second copy of your master key, wrapped under the phrase. That is what lets the phrase stand in for the sync password on a device that has never seen this vault.

The ceremony works like this:

• The words appear numbered, one per line.
• Copy to clipboard writes them out still numbered, one per line.
• You then type back three words from randomly chosen positions. The comparison trims whitespace and ignores case.

Later, when you enter the phrase to unlock sync, the parser is deliberately forgiving. It lowercases the input and splits on anything that is not a letter, so the numbered format the copy button produces pastes back in cleanly.

Forget the password and the phrase still works. Lose both, and the copies on the server cannot be recovered by you or by anyone else, including Jotura. The plain markdown files on your disk are unaffected either way, so this is a loss of the synced copy and of any device you have not already unlocked.

To replace a phrase you no longer trust, expand Security & recovery in Settings and use New recovery phrase. It asks for your sync password, generates a fresh phrase, invalidates the old one, and runs the same show-once ceremony.

Unlocking sync on a device

A device that has the vault but not the cached key sits in a “needs key” state. Sync pauses there, and nothing else does. You put the key back through the Unlock sync dialog. There are three ways to reach it: click the sync pill in the status bar, click through the banner above the tab bar, or use the Unlock sync… button on the Sync password needed row in Settings.

The dialog opens in password mode, titled “Unlock sync”, explaining “Sync is paused until you enter your sync password. Your notes on this device stay fully usable meanwhile.” Type the password and press Unlock sync.

Below the password field sits Forgot password? Use recovery phrase, which switches the dialog to a second mode titled “Use recovery phrase”. This mode asks for more than the phrase:

Field	Requirement
Recovery phrase	All 12 words. Short input is refused with “Enter all 12 words of your recovery phrase.”
New sync password	At least 12 characters, or “New sync password must be at least 12 characters.”
Confirm new sync password	Must match, or “Passwords don’t match.”

Recovery is not a read-only unlock. Coming back in with the phrase always sets a new sync password at the same time, so have one ready before you start. The new password is re-wrapped over the same master key and pushed to the server, and the recovery phrase itself keeps working afterward. Back returns you to password mode, and Unlock with phrase submits.

Devices

Each device signs in to the same account, then gets the vault in one of two ways.

Restore the vault from the cloud. In Settings, Restore vault from cloud offers to “Pick a vault from your account and download it to a local folder.” You choose a remote vault, choose an empty local folder, and then authenticate with either your sync password or the recovery phrase. The phrase is entered in a 12-cell grid, and pasting the whole phrase spreads the words across the cells. As in the unlock dialog, the phrase path also asks you to set a sync password for this device. It must be at least 12 characters, and shorter input is refused with “Sync password must be at least 12 characters.”

Restoring shows live progress as “Restoring <n> of <total> notes…” with a Cancel button, and a cancelled restore can be resumed later. If the current vault has unsaved changes, the app saves them first after asking “You have unsaved changes in the current vault. They’ll be saved before restoring. Continue?”

Open a folder that already holds the vault. If the files are already on the device, opening that folder and unlocking with the sync password is enough.

A signed-in device that has the vault but not the key is never blocked. Reading, writing, and search all continue as normal, and edits queue up until the key arrives.

Forget key on this device in Security & recovery clears the cached key deliberately. It confirms with “Forget the sync key on this device? Sync pauses until you re-enter your sync password (or recovery phrase). Your notes stay fully usable on this device.” The desktop app and the jotura CLI read the same per-vault key cache, so unlocking in either one resumes sync for both. Forgetting is less symmetrical: jotura sync logout deletes the cache file but does not clear the key from the memory of a desktop app that is already running. See Sync and shares from the CLI for the command-line half.

There is no device manager. The app has no device list, no per-device revocation, and no way to sign another machine out remotely. The only device-level control is Forget key on this device, which by definition needs the device in your hands. Settings does show a read-only Device ID row, described as “Unique per install. Both devices must be signed in to the same account.” If you lose a machine outright, there are two honest options, and neither is a clean revocation. You can change your sync password, which does not evict a device that already holds a cached key. You can also sign out of the account from a device you still have.

What actually syncs

Sync covers the files in your vault that Jotura recognizes as text or as documents. Anything starting with a dot is skipped, so .jotura/ and its index, trash, templates, and sync database stay local to each machine.

Category	Extensions
Text	md, markdown, mdc, txt, rst, org, tex, json, yaml, yml, toml, csv, tsv, xml, html, htm, css, scss, sass, js, mjs, ts, tsx, jsx, py, rb, rs, go, java, kt, swift, c, cpp, h, hpp, sh, bash, zsh, fish, ini, conf, env, sql, log, ps1, bat
Documents and images	pdf, docx, doc, xlsx, xls, pptx, ppt, odt, ods, odp, rtf, epub, png, jpg, jpeg, gif, webp, svg, bmp, ico, heic, heif, avif, tiff, tif

A file whose extension is outside both lists is never uploaded, and neither is a file with no extension at all, so a LICENSE or a Makefile stays on the machine that created it. When you import a document, the searchable markdown version Jotura generates is a sibling file such as report.pdf.md, which is ordinary markdown and syncs like any other note. Documents covers that pipeline.

The size limit is a client-side rule, not a server one. Jotura refuses to upload a file larger than 16 MiB (16,777,216 bytes), dropping the pending upload rather than retrying against a cap forever, and writes a line to the log. The file itself stays on your disk untouched, and nothing in the interface flags the skip. The server’s own limit is higher, so raising the client constant is the only thing standing between a large file and the cloud copy.

A change on disk queues an upload after a one second debounce, so a burst of edits collapses into one push. Downloads are polled every five seconds, and bringing the app window back into focus also triggers an immediate pull. This is not real-time collaboration. Two people typing into the same paragraph at the same moment see each other’s text a few seconds later, not as it is typed.

Sync status and controls

The Settings Status row reports one of a fixed set of messages once sync is enabled.

Status text	Meaning
Idle. All changes pushed.	Nothing is queued.
Registering vault on the server…	First-time setup is still running.
Syncing <n> of <n> notes…	An upload is in progress.
Syncing…	An upload is in progress with no count yet.
Pulling <n> of <n> notes…	A download is in progress.
Error: <message>	The raw error from the last attempt.
Offline. Will retry when online.	The app has no network.
Not registered.	The vault has not been registered on the server.
Not signed in.	No account session.
Sync key needed. Unlock sync with your password.	The key is not cached on this device.
Paused. Server copy preserved. Resume to push pending edits.	You paused sync yourself.

Two Settings states sit outside that list because they replace the Status row entirely. With no vault open, the row is labelled Status and reads “Open a vault to enable sync.” With a vault open but no cached key, the row is labelled Sync password needed and reads “Sync is paused until you enter your sync password. Notes stay fully usable meanwhile.”

The same states surface in two smaller places. A pill sits in the status bar, and a banner can appear above the tab bar.

Surface	State	Behavior
Pill	Sync paused	A button. “Sync is paused until you enter your sync password. Click to unlock.”
Pill	Sign in	A button. “You’re signed out. Click to sign in and resume sync.”
Pill	Synced	Static text, “All changes pushed”.
Pill	Subscription needed	Static text.
Pill	Sync error	Static text carrying the raw message.
Pill	Offline	Static text, “Sync will retry when online”.
Pill	Paused	Static text, quoting the app: “Sync is paused. Resume from Settings → Sync.”
Banner	Sync paused. You’re signed out.	Dismissible, remembered per vault.
Banner	Sync paused. Enter your sync password.	Dismissible, remembered per vault.

The pill shows nothing at all when sync is not configured, and nothing during in-flight uploads and downloads, because the status bar already shows progress for those.

The controls available in Settings are:

Control	Where	What it does
Pause sync / Resume sync	Account & sync	Stops and restarts both directions. The server copy is preserved while paused.
Change sync password	Security & recovery	Re-wraps the master key locally, then updates the salt, parameters, and wrapped key on the server. Minimum 12 characters. Other devices keep working with their cached key until they need to unlock again, at which point they need the new password.
New recovery phrase	Security & recovery	Generates a fresh phrase and invalidates the old one. Requires the sync password.
Forget key on this device	Security & recovery	Clears the cached key. Sync pauses, local editing continues.
Force re-sync	Account & sync, in the sync diagnostics rows	Resets the local cursor and re-fetches the whole manifest. Confirms with “Re-fetch the entire manifest from the server? Local pending edits are kept.”
Restore vault from cloud	Account & sync	Downloads a remote vault into an empty local folder.

When you are signed in with a vault open, a set of diagnostic rows also appears in Account & sync and refreshes every two seconds. The rows are Account, Device ID, Vault ID, Pending ops, Server version, Last push, Last pull, Last push error, and Last pull error. Force re-sync sits at the bottom of that group. Note that the Diagnostics sub-group under Advanced is a different thing, holding Copy diagnostics and the log file path. The full list of Settings sections is on the Settings reference page.

When the same note changes in two places

Jotura does not create conflict files and does not ask you to pick a winner. Divergence is resolved by a three-way merge, and the merged text is written to the real file. Either way the app announces “Merged changes from disk” in the same words, but there are two mechanisms behind that message, with different ideas of the base version.

Mechanism	When it fires	Base version
Pull-side merge	A downloaded change lands on a file that also changed locally	The last plaintext both sides agreed on
Editor-side merge	A save finds the file on disk has changed underneath it, from any source at all	The tab’s last clean content, retried up to three times

The editor-side merge is not a sync feature. It fires for an external edit from any tool, sync or not, which is why the message shows up in vaults that have never been synced. Merged results are queued for upload so the other device converges on the same text.

Two cases fall outside merging.

• Content that cannot be merged as text, which means binary files, non-UTF-8 content, and structural mismatches, keeps your local bytes. The remote change is not applied to that file on this device.
• A note that was deleted or moved outside the app is the only case that asks you anything. A banner appears reading “This note was deleted or moved outside the app.” with two buttons, Close tab and Recreate with my version.

One piece of in-app wording is out of date on this point. The Force re-sync helper text in Settings still says a diverged file “becomes a .conflict-* sibling”. The app does not create those files. Divergence is auto-merged, or your local bytes are kept, as described above.

Sharing a folder or a file

A share stays exactly where it is in your vault. Sharing does not move the files, and it does not copy them to a special location. What changes is that the folder or file becomes its own encrypted sync unit with its own key, sealed for each member.

Both sides need a Jotura account with an active subscription. If your own account lacks one, the create dialog says so before anything else: “Sharing runs on Jotura Sync. You and the people you invite each need an active subscription.” An attempt to share anyway fails with “Sharing needs an active Jotura Sync subscription. See the plans below.”

What can be shared

You can share any folder, and any single file that sync recognizes, which is the full extension list in the table above. A PDF or an image can be shared on its own, not only a markdown note. Three things are refused, each with its own message:

Target	Message
The vault root	“cannot share the vault root”
A path that overlaps an existing share	“this path overlaps an existing share”
Anything else, such as a file type sync does not carry	“only folders and synced note files can be shared”

Overlap is checked in both directions. You cannot share something inside an existing share, and you also cannot share a parent folder that contains one. If team/docs is already shared, then team/docs/notes and team are both refused, and you have to unshare first if you want the wider folder instead.

Starting a share

There are three ways in:

• Right-click a folder or a file in the file tree and choose Share…. The item is offered for anything not already shared, other than the vault root.
• Run Share Current Note… from the command palette. It has no keyboard shortcut, and it does nothing when the active tab is not a markdown note. This entry point is the only markdown-only one.
• Use the Shared pane in the sidebar and pick a row’s menu.

The dialog title tells you which mode you are in. It reads Share "<name>" while creating a share, and Sharing "<name>" once the share exists and you are managing it.

The create dialog explains what will happen before you commit. For a folder it reads: “<name> and everything inside stays right where it is in your vault. It syncs to the people you invite, who’ll see it under ‘Shared with me’ in their own vault.” For a single file the wording drops “and everything inside”. A second line adds “You’ll invite people by email in the next step, as editors or viewers.” Clicking Share turns the target into a share and moves you to the manage view.

Inviting people

The manage view has an invite form with an email field, a role select, and an Invite button. Under it sits the hint “Invitees accept in Jotura on desktop (Mac, Windows, Linux) or Android.” A malformed address is rejected with “Enter a valid email address.”, and a member list that fails to load reads “Couldn’t load the member list. Check your connection and reopen this dialog.”

Role	Select label	What it allows
Editor	Can edit	Read and write. Their edits sync back to you.
Viewer	Can view	Read only. Writes into the mount are refused.
Owner	Not selectable	The person who created the share. Only the owner can invite, change roles, remove members, or unshare.

A viewer role stops writes from syncing. It does not stop anyone reading, screenshotting, or copying content their app has already downloaded, and the dialog says as much: “Viewers can’t save changes. They could still copy what they can see.”

Sharing is managed on desktop only. The Android app can list shares, accept invites, sync a share, and leave one, but it cannot create a share, invite anyone, change roles, or remove members.

What happens after you click Invite depends on whether that email already belongs to a Jotura account.

Outcome	Message
Already an account, added directly	“<email> has access now. It’s live on their devices.”
Invite created and emailed	“Invite sent. <email> has been emailed. They can accept in Jotura on desktop or Android.”
Invite created, email failed	“Invite created, but the email to <email> could not be sent. Ask them to sign in to Jotura with that address, and the invite will be waiting.”
Already a member	“<email> is already a member of this share.”
No subscription on your account	“Inviting needs an active Jotura Sync subscription.”

If the manage view itself finds your entitlement missing, the invite form is replaced by “Inviting people needs an active Jotura Sync subscription.”

What the other person needs

The recipient needs three things: a Jotura account on the invited email address, an active Jotura Sync subscription, and the app on desktop (Mac, Windows, or Linux) or Android.

They do not need to enable sync on their own vault first. A share is its own sync unit, keyed off the account identity rather than any vault master key, and share discovery runs even on a vault where personal sync was never configured. Their own notes can stay entirely local while a shared folder syncs beside them.

Accepting an invite

A banner appears in their app reading “<your email> shared ‘<name>’ with you” followed by “(you can edit).” or “(view only).” and “It’ll appear under ‘Shared with me’ in your vault.” The banner has Accept and Dismiss.

Accepting can land in one of three places:

• Accepted. The share mounts under Shared with me/ in their vault and starts syncing. The mount is normally Shared with me/<name>. If that path is already taken by another share or by an existing folder, Jotura appends a counter instead, mounting at Shared with me/<name> (2), then (3), and so on.
• Waiting for the owner. The banner changes to “Almost there: waiting for the owner’s app to confirm.” The share key has to be sealed for the new member by a device that already holds it, so your app needs to be running and online. The banner adds that this usually takes under a minute, and share discovery runs at most once every 60 seconds.
• Subscription needed. The banner reads “‘<name>’ needs Jotura Sync to open. Shared content syncs end-to-end encrypted, and that takes an active subscription.” with a Get Jotura Sync button.

Shared content is a normal part of the recipient’s vault once mounted. It is indexed, searchable, and reachable from wikilinks, the same as any other note. See Search for how that works.

Watching a share

The Shared pane in the sidebar has two sections, Shared with me and Shared by me. Each row shows a status dot, the name, and a role chip. The dot’s tooltip is one of a fixed set.

Dot tooltip	Meaning
Not syncing yet	The share has not been set up locally.
Up to date	Everything is pushed and pulled.
Syncing…	Transfer in progress.
Needs your sync key	This device does not have the key cached.
Your role changed. Edits here can’t be saved	You were demoted to viewer while working.
Subscription needed to keep this share syncing	Entitlement lapsed.
Sync error: <message>	The raw error from the last attempt.
Offline, will retry	No network.
Paused	Sync is paused.
Not syncing	The unit is not running.

An unmounted share shows a Set up action. A mounted one gets a … menu with Manage sharing… or Details…, Sync now, and Unshare or Leave.

Changing roles and removing people

In the manage view, the owner sees every member with a role select and a Remove button, plus any pending invites shown as “Invited · Editor” or “Invited · Viewer” with a Cancel button.

Changing a role takes effect on the next sync. When someone is demoted to viewer while they have the share open, their app surfaces “Your role changed. Edits here can’t be saved” rather than silently discarding work.

Removing a member confirms first: “Remove <email> from this share? Their local copy moves to their trash, and they lose access right away.”

Removal is not a key rotation. The removed person loses server access immediately and their local copy is moved to their vault trash, but the share’s master key is not rotated. Anything they already synced and copied out of Jotura stays readable to them, and no revocation in any product can change that.

Stopping a share

Action	Who	Confirmation	Result
Unshare	Owner	“Stop sharing? Everyone you invited loses access. The files stay right where they are in your vault.”	The files stay put and rejoin your personal sync. Everyone else loses access.
Leave share	Member	“Leave this share? Your local copy moves to the vault trash, and you’ll need a new invite to rejoin.”	Your mounted copy moves into the vault’s own trash folder.

Both leaving and being removed move the local copy into <vault>/.jotura/trash/, not the operating system trash. The desktop app has no trash browser, so restoring from there is a CLI operation. Creating, moving, and deleting covers jotura trash restore.

Shares from the command line

The jotura CLI is share-aware for reading and editing, but share management stays in the desktop app. There is no CLI command to create a share, invite someone, change a role, or accept an invite. A machine that only has the CLI cannot receive a new share either, because mounting happens when the desktop or Android app runs discovery. Once a share is mounted, the CLI works inside it normally.

List shares with their mount point, role, and sync state:

jotura shares list --json

Check the sync key and pending work. This command respects --json, and its text form prints one line per share:

jotura sync status

Cache the sync key for a vault so later CLI runs do not prompt. With no flags it prompts for the sync password without echoing it:

jotura sync login

Two flags change how that works. --passphrase-stdin reads the secret from standard input instead of prompting, and --recovery-phrase prompts for the 12-word phrase instead of the password:

jotura sync login --recovery-phrase

sync login emits JSON whether or not you pass --json, in the form { "status": "keyCached", "vault": "..." }.

Three exit codes matter here.

Code	Name	When
9	InvalidArgs	A wrong sync password or an invalid recovery phrase. There is no dedicated authentication code.
12	SyncNotEnabled	sync login, sync logout, or sync drop-path on a vault with no sync configured. sync status deliberately never exits 12; it reports enabled: false instead.
15	ReadOnlyShare	A write targets a path inside a viewer-role share mount. The error carries path, shareId, and mountRel.

There is deliberately no override for exit 15. A forced write into a viewer mount would never sync and would be overwritten by the next remote change. The fix is to ask the owner for editor access. Full details are in Sync and shares from the CLI and Exit codes and JSON output.

Related pages

• Version history covers the server-side version list that sync makes possible, and how it merges with local autosave snapshots.
• Troubleshooting covers what to do when sync stalls, including the diagnostics bundle.
• Settings reference lists every control in the Account & sync section alongside the rest.
• Documents covers imported files and the converted markdown siblings that sync with them.
• Sync and shares from the CLI covers the same subject from the terminal.