Getting started

Jotura edits an ordinary folder of markdown files on your disk. There is no library to import into, no database to build, and no account to create before you can write.

This page covers installation, opening a vault, what Jotura writes to disk, how saving works, and the parts of the window you will use every day.

Install the app

The one-line installer

The install script works in six steps, in this order:

1. It fetches the release manifest from releases.jotura.io.
2. It downloads the installer artifact for your operating system and CPU.
3. It verifies the artifact’s SHA-256 checksum against the manifest. Nothing is installed if the checksum does not match.
4. It installs the desktop app and puts the jotura command-line tool on your PATH.
5. It installs the Jotura agent skill for any AI coding agents it finds.
6. It launches the app.

On macOS and Linux:

curl -fsSL https://jotura.io/install.sh | bash

On Windows, in PowerShell:

irm https://jotura.io/install.ps1 | iex

Re-running either script upgrades an existing install in place. You can read both scripts first: they are published at jotura.io/install.sh and jotura.io/install.ps1.

Where the one-liner puts things

Platform	The app	The CLI	Also written
macOS	/Applications/Jotura.app, unpacked from the universal .app.tar.gz with the quarantine flag cleared	A symlink at /usr/local/bin/jotura pointing into the bundle	Nothing else
Linux, default	~/.local/share/jotura/Jotura.AppImage	~/.local/bin/jotura, extracted from the AppImage	~/.local/share/applications/jotura.desktop and ~/.local/share/icons/jotura.png
Linux with --deb	A system package, installed with apt-get or dpkg	/usr/bin/jotura	Nothing else
Windows	The MSI’s install directory	jotura.exe in that same directory	Nothing else

Three caveats sit with those rows. The macOS symlink needs sudo, and if you decline it the CLI still runs from inside the app bundle. On Linux the script warns you when ~/.local/bin is not already on your PATH. The --deb path also needs sudo, and the script refuses that flag without it.

The Windows MSI runs with msiexec /passive, so expect a Windows User Account Control elevation prompt. The macOS and Linux script may ask for your login password.

Installer flags

The macOS and Linux script takes flags after a -- separator when you pipe it into bash:

curl -fsSL https://jotura.io/install.sh | bash -s -- --no-launch --skills none

Flag	Effect
--no-launch	Do not launch the app when the install finishes.
--skills <mode>	Which AI agents get the Jotura skill. Accepts all, claude, codex, gemini, copilot, or none.
--deb	Linux only. Install the .deb system package instead of the AppImage.
-h, --help	Print the script’s help and exit.

Leaving --skills off installs the skill for every agent detected on the machine. That default has no name in this script, so --skills detect is rejected with invalid --skills value 'detect'.

The Windows script takes parameters rather than flags, and PowerShell cannot pass parameters through irm ... | iex. Download the file first if you need them:

irm https://jotura.io/install.ps1 -OutFile install.ps1
.\install.ps1 -NoLaunch -Skills none

-NoLaunch skips the launch at the end. -Skills accepts detect, all, claude, codex, gemini, copilot, or none, and detect is its default. That named mode is the one difference between the two scripts.

Both scripts also honor two environment variables that exist for continuous integration rather than everyday use. JOTURA_INSTALL_DRYRUN=1 stops after the download and checksum check, and JOTURA_MANIFEST_URL overrides the release manifest URL.

Agent detection is the presence of a ~/.claude, ~/.codex, ~/.gemini, or ~/.copilot directory. When none of them exists, the script prints the command to install a skill later yourself:

jotura skill install all --force

The same command accepts claude, codex, gemini, or copilot in place of all. The agent surface is documented separately in The agent surface.

Manual installers

Every artifact is linked from the download page, which serves version-stamped filenames such as Jotura_0.7.0_universal.dmg.

Platform	Artifact	Install
macOS, Apple Silicon and Intel	Universal .dmg	Open the disk image and drag Jotura to your Applications folder, replacing any earlier version.
Windows 10 and 11, x64	.msi	Run the installer.
Linux x64 and arm64	.AppImage	Mark it executable and run it. See the commands below.
Linux x64 and arm64	.deb	Install it with dpkg, or double-click it in your package manager.
Android arm64	Google Play, or a direct .apk	Install from Play for one-tap updates, or open the APK and allow installs from your browser when Android asks.

For the x64 AppImage, from the directory you downloaded it into:

chmod +x ./Jotura_*_amd64.AppImage
./Jotura_*_amd64.AppImage

For the x64 .deb:

sudo dpkg -i ./Jotura_*_amd64.deb

On arm64 machines, substitute _arm64 for _amd64 in both commands.

Two operating-system warnings are expected on the manual path, because the builds are not signed with a paid developer certificate. The one-line installer avoids the macOS one by clearing the quarantine flag itself.

On macOS, recent versions say that Apple could not verify Jotura is free of malware. To get past it:

1. Open System Settings, then Privacy & Security.
2. Scroll to the Security section and click Open Anyway next to the Jotura message.
3. Confirm with Touch ID or your password.
4. Click Open Anyway once more in the dialog that follows.

Later launches work normally. On Windows, SmartScreen warns that this is an unrecognized app: click More info, then Run anyway.

Updates

The desktop app updates itself. It checks five seconds after launch and then every four hours, so a version released while you are working may take a while to appear. Development builds never check.

When a check finds a new version, the status bar at the bottom of the sidebar shows Update ready - restart. That label appears before anything has been downloaded. Clicking it downloads and installs the update, showing Updating… {percent}% and then Restarting… before the app relaunches. A failed download puts the label back to Update ready - restart so you can try again.

The Linux .deb package is the exception: it does not auto-update. Re-run the install script or install a newer .deb to upgrade it.

Getting the CLI on your PATH

The jotura command-line tool ships inside every desktop installer. How it reaches your PATH depends on the platform.

Platform	How the CLI gets on PATH
macOS	Open Settings, expand Advanced, then Command-line tool, and click Install. Jotura runs an osascript command with administrator privileges to symlink /usr/local/bin/jotura to the bundled binary, so macOS prompts for an admin password. Remove it later with sudo rm /usr/local/bin/jotura.
Windows	The MSI adds its install directory to the system PATH, so nothing is needed. Terminals that were already open keep their old PATH until you restart them, which is the usual reason jotura looks missing right after an install.
Linux .deb	The package installs the binary at /usr/bin/jotura. Nothing to do.
Linux AppImage	Jotura copies the binary to ~/.local/bin/jotura for you. That directory must already be on your PATH.

On Windows and on the Linux AppImage, Jotura shows a one-time prompt at startup offering to do this for you. It records that the prompt was shown whether you accept or decline, so it never asks a second time and cannot be brought back.

The Settings card is the way back. It appears on macOS, Windows, and the Linux AppImage, and is absent only on the Linux .deb, where the package has already handled PATH. One Windows quirk is worth knowing: the app decides whether the CLI is installed by reading your user PATH, while the MSI writes the system PATH. So Jotura can report the tool as not installed when it already works, and clicking Install simply adds a second, user-level entry.

Full CLI setup, including vault selection and shell completion, is covered in Install and setup.

Open a vault

A vault is a folder. Jotura itself never creates one, but the system folder picker on macOS and Windows has its own New Folder control, so you can make an empty one without leaving the dialog.

1. Click the vault button in the sidebar header. Before a vault is open it reads Open vault…, and afterwards it shows the vault’s folder name.
2. Pick a folder in the dialog titled Select a vault folder.
3. The folder name becomes the vault name, and the tree fills with whatever markdown files were already there.

If you select something that is not a directory, the open fails rather than creating anything. Nothing is copied, converted, or moved: your existing files stay where they are, readable and writable by every other tool on your machine.

What the first open writes

Opening a vault does write to the folder, and this catches people out. Daily notes are enabled by default, so Jotura creates an empty note for today and for each of the next 13 days, at Daily/<year>/<month>/<YYYY-MM-DD>.md.

That count is the Auto-create window setting under Settings, Daily Notes. Its default is 14 and its range is 1 to 60. Turning off Enable daily notes in the same section stops the writes entirely, and also hides the calendar in the right sidebar. The feature itself is covered in Daily notes, tasks, and templates.

Switching and reopening vaults

The vault button switches vaults at any time. Picking the vault that is already open does not rebuild the search index, but it is not free either: it closes every open tab and collapses the folder tree, so do it deliberately.

On the next launch, Jotura reopens the last vault automatically. The path is stored as lastVaultPath in the app’s settings file, and it is the only setting that decides which vault opens. Other state also lives outside the vault, including the sidebar widths and the per-vault list of recently closed tabs.

If the vault you want is already in your Jotura account, there is a second route onto a new machine. Settings, Account & sync, Restore vault from cloud downloads a remote vault into an empty local folder. See Sync and sharing.

Opening an existing Obsidian vault

An Obsidian vault is already a folder of markdown files, so you point Jotura at it and start working. There is no export step and no migration.

Jotura’s file tree skips dot-prefixed files and folders at every level, so Obsidian’s .obsidian configuration directory stays on disk untouched and simply never appears in the tree. Round-trip fidelity is a tested invariant: opening a note and saving it without edits produces a byte-identical file, held in place by 63 fixtures. The daily notes described above are the exception to “nothing changes”, since they land in the shared folder like any other note.

Running both apps against the same folder works, with one caveat about who resolves what. Jotura never prompts about a file that changed on disk: it merges the disk version into your open editor, as described under saving below. That protects the Jotura side only, so avoid having the same note open for editing in both apps at once.

Some things do not carry over, and it is worth knowing before you commit.

Obsidian feature	In Jotura
Community plugins	No plugin system. Dataview queries, Templater syntax, and Excalidraw drawings sit in your notes as plain text.
Graph view and Canvas	Neither exists.
Inline hashtags as tags	The Tags pane reads the tags: key in a note’s frontmatter only. A #hashtag in the body is decorated in the editor and clicking it runs a keyword search, but it never appears in the Tags pane.
Themes	Jotura has its own appearance settings. Theme, editor font, and font sizes are in Settings.
Obsidian Publish	No publishing feature.

Wikilinks in [[double brackets]] keep working. Jotura decorates them in the editor, marks links whose target is missing, and opens the target when you click one. Clicking a link with no target asks No note named "{name}". Create it?, so a broken link is one click from becoming a real note. A longer walkthrough lives in the switching from Obsidian guide.

Where files live on disk

Your notes are the folder you picked, and they stay ordinary files. Jotura adds up to two visible folders in the vault root, plus one hidden directory for its own state.

Path	What it holds	When it appears
<vault>/Daily/	Daily notes, filed as <year>/<month>/<YYYY-MM-DD>.md. Ordinary notes in every other respect, including sync and search.	On vault open, while daily notes are enabled. The folder name is fixed at Daily and has no control in Settings.
<vault>/attachments/	Imported documents, and files you paste or drop into a note.	The first time you import something. Rename it under Settings, Advanced, Files & folders, Default document folder.
<vault>/.jotura/	Jotura’s own state for this vault, detailed below. The file tree, the search index, and sync all skip it.	On vault open.

Inside that hidden directory:

Path	What it holds
<vault>/.jotura/index/	The Tantivy full-text search index.
<vault>/.jotura/trash/	Soft-deleted notes, each with a .trashmeta JSON sidecar recording the original path, size, and time.
<vault>/.jotura/templates/	Note templates, one markdown file per template. Nested names such as work/standup are allowed.
<vault>/.jotura/history/	Local autosave snapshots for version history.
<vault>/.jotura/sync.db	Sync state, present only when cloud sync is enabled for this vault.
<vault>/.jotura/vectors.db	The semantic search index, present only when semantic search is enabled.
<vault>/.jotura/shares/	The share registry and per-share sync state.
<vault>/.jotura/write.lock	The cross-process write lock that keeps the app and the CLI from writing over each other.

Imported documents such as PDFs and Word files are stored as themselves, with a converted markdown mirror written as a sibling file. The tree hides the mirror, so report.pdf.md never appears next to report.pdf. See Documents.

Application settings live outside the vault, in the operating system’s configuration directory.

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

The same jotura directory holds the sync key cache in sessions/, the account tokens in auth.json, and the downloaded embedding model under models/ if you enable semantic search.

One caveat about that settings file. It is written with a plain file write rather than the write-to-temporary-file-and-rename approach used for notes. A crash partway through a settings write can truncate it, and a settings file that fails to parse is silently replaced by defaults on the next load. Your notes are never at risk from this, because note writes are atomic and fsynced, but a lost preference is possible.

Note contents are never encrypted on disk. At-rest protection is the operating system’s job, through FileVault, BitLocker, or the equivalent.

Encryption applies to cloud sync, where notes are encrypted on your device before upload. See Security and Sync and sharing. Cloud sync requires a paid subscription, priced on the pricing page.

Saving happens on its own

There is no save shortcut. Cmd+S and Ctrl+S are not bound to anything in Jotura, deliberately, because every edit is saved for you.

Trigger	When it fires
Autosave timer	1000 milliseconds after your last change.
Blur flush	When the editor loses focus.
Visibility flush	When the window becomes hidden, for example when you switch to another application.

The same three triggers apply in the WYSIWYG editor, in source mode, and in plain-text tabs. Tabs opened read-only never become dirty and therefore never autosave. All saves pass through a serial queue, so an autosave timer and a blur flush cannot collide.

A tab with unsaved changes shows a small dot after its title in the tab bar. In practice the dot appears and disappears within a second of you pausing. Screen readers hear Saved when a save completes, since there is nothing on screen to watch.

If a note changes on disk while you have it open, Jotura does not interrupt you. It merges three versions silently: the content the tab started from, your editor content, and the fresh file on disk. It retries up to three times and announces Merged changes from disk to screen readers. Conflict files are never created.

The one case that does ask you is a note that vanished. If the file was deleted or moved outside the app, the editor shows a banner reading This note was deleted or moved outside the app. It offers two buttons: Close tab, and Recreate with my version, which writes your editor content back to the original path.

A first tour of the window

The sidebar

The left sidebar has a header, a pane switcher, the pane itself, and a status bar pinned to the bottom. The header carries the Jotura logo, the vault button described above, and a settings gear. Below it sits an icon-only pane switcher with four panes.

Pane	What it shows
Files	The vault’s folder tree.
Search	Keyword search with arrow-key navigation and three toggles, labelled in the UI with the literal glyphs Aa for case sensitive, W for whole word, and "" for phrase.
Tags	Tags declared under a tags: key in note frontmatter. Selecting one lists the notes that carry it. Hashtags typed in a note body are not collected here.
Shared	Shares you have received and shares you have created.

The Files pane adds two buttons, Expand all folders and Collapse all folders. While the search index is building, a strip reads Indexing… {done}/{total}.

The status bar shows just the app version when nothing is happening. During background work it shows a spinner and the single highest-priority task, in the order converting, embedding, indexing, syncing, with a +{n} badge and a tooltip when more than one is running.

Three of those four read {Name} {done}/{total} · {eta} left. Syncing is the exception: it reads Syncing {n} pending, or Syncing … when nothing is queued, and never shows an estimate.

Press Cmd+\ or Ctrl+\ to toggle the sidebar. Collapsed, it becomes a single Show sidebar button.

You can resize the sidebar by dragging its edge, between 200 and 600 pixels, defaulting to 300. The drag handle is also focusable with Tab, and once focused the left and right arrow keys resize in 16-pixel steps. The width is saved immediately. The right sidebar resizes by mouse only.

The file tree

The tree is fully keyboard navigable once focus is inside it.

Key	Effect
Arrow Down, Arrow Up	Move through the visible rows. Children of collapsed folders are skipped.
Arrow Right	Expand a collapsed folder, or move down one row if it is already expanded. No effect on files.
Arrow Left	Collapse an expanded folder, otherwise jump to the parent folder’s row.
Enter	Open the focused file.
F2	Start an inline rename on the focused row.

Inline rename and create inputs both submit on Enter and cancel on Escape. They differ on blur: clicking away from a rename submits it, while clicking away from a create cancels it. A create input preselects the name up to the last dot, and a rename selects the whole name. Double-clicking a file row also starts a rename.

Drag a file or folder onto another folder to move it. Jotura implements the move as a rename, so the file keeps its content and its version history. Dropping a folder into itself or into one of its own descendants is refused, with the announcement A folder can't be moved into itself.

Dropping files from your operating system onto the tree does something different. It imports them into the folder you dropped on, or into the vault root if you dropped on empty space. This is the main entry point for adding PDFs and other documents.

Right-clicking a row opens a context menu. Which items appear depends on the row.

Item	Appears for
Open in browser	HTML files.
Open original externally	Imported documents and plain-text files.
Reveal in File Explorer, Reveal in Finder, or Show in folder	Every row. The wording follows your platform.
Copy path	Every row. Copies the vault-relative path and announces Path copied.
New note	Every row.
New note from template	Folders.
New folder	Folders.
Expand all folders, Collapse all folders	Every row.
Share…	Rows that are not already shared and are not the vault root.
Manage sharing…	Share mount roots.
History	.md files only.
Rename	Every row.
Move to trash	Every row.

Move to trash moves the entry into <vault>/.jotura/trash/, not your operating system’s trash, and announces Moved "{name}" to trash. The desktop app has no trash browser: restoring or permanently purging trashed items is done from the CLI, covered in Creating, moving, and deleting.

Tabs

The tab bar appears only once something is open.

• A dot after the title means unsaved changes. The close control is a ×.
• Drag tabs to reorder them. Search tabs and history tabs are pinned at the far left, cannot be dragged, and cannot be dropped onto.
• Right-click a tab for Close, Close others, and Close all.
• A vertical scroll wheel scrolls the bar horizontally, and the active tab scrolls itself into view.
• Closed tabs are remembered, 20 of them, deduplicated by path and stored per vault, which is what Cmd+Shift+T or Ctrl+Shift+T reopens.

Action	Shortcut
Close active tab	Cmd+W or Ctrl+W
Reopen last closed tab	Cmd+Shift+T or Ctrl+Shift+T
Next tab	Cmd+Tab or Ctrl+Tab
Previous tab	Cmd+Shift+Tab or Ctrl+Shift+Tab

The Command and Control keys are interchangeable for these global shortcuts on every platform, because the handler accepts either modifier. Two consequences follow from the tab-switching pair specifically.

The first affects the editor. Jotura claims the modifier-plus-Tab combination and cancels the browser default, so Tab does nothing inside the editor while Cmd or Ctrl is held. Indenting a list item needs Tab pressed on its own.

The second affects macOS. The system application switcher normally claims Cmd+Tab before the app ever sees it. If tab switching does not respond there, use Ctrl+Tab or the Next Tab and Previous Tab entries in the command palette.

Quick open

Press Cmd+P or Ctrl+P to toggle quick open, then type part of a file name.

• The match is a fuzzy match on the file’s base name only. It does not search the folder path and it does not search note content.
• There is no > prefix for commands and no #tag filter. Those are separate surfaces.
• Typing is debounced by 80 milliseconds and the list shows at most 20 results.
• Arrow Down and Arrow Up move through the list, which clamps at both ends rather than wrapping, and Enter opens the highlighted file. Escape closes.
• The placeholder reads Search files by name… and an empty result set reads No files match.
• Closing quick open deliberately keeps your query, so reopening shows it again. The input is selected, so typing replaces it.

For content search, tags, and semantic search, see Search.

The command palette

Press Cmd+Shift+P or Ctrl+Shift+P to toggle the command palette. It lists every command with its group and, where one exists, its shortcut. The placeholder reads Type a command… and an empty result set reads No commands match. Filtering is a fuzzy subsequence match on the command name that rewards consecutive runs and prefix matches.

There are eighteen commands.

Command	Group	Shortcut
View: Toggle Sidebar	View	Cmd/Ctrl+\
Editor: Toggle Source Mode	Editor	Cmd/Ctrl+Shift+E
Open Settings	App	none
Search Vault	Search	Cmd/Ctrl+Shift+F
Open Search Panel	Search	none
Open Quick Open	Search	Cmd/Ctrl+P
Close Tab	Tabs	Cmd/Ctrl+W
Reopen Recently Closed Tab	Tabs	Cmd/Ctrl+Shift+T
Next Tab	Tabs	Cmd/Ctrl+Tab
Previous Tab	Tabs	Cmd/Ctrl+Shift+Tab
New Note (in vault root)	Files	none
New Note from Template…	Files	none
Share Current Note…	Files	none
History for Current Note	Files	none
Insert Link to Note…	Editor	Cmd/Ctrl+L
Open Command Palette	App	Cmd/Ctrl+Shift+P
Export as HTML…	Editor	none
Print / Save as PDF	Editor	none

Two of those shortcuts need editor focus. Cmd/Ctrl+L and Cmd/Ctrl+Shift+E are bound inside the editor, not globally, so from anywhere else in the app you reach them through the palette. The full chord list, including formatting, lists, and tables, is in Keyboard shortcuts.

Two commands can decline to run, and neither says so. History for Current Note does nothing when the active tab is a search or history tab, or when the file is not a .md note. Share Current Note… makes the same search-and-history check but no markdown check, so it will open the share picker for any file tab.

Creating your first note

New Note (in vault root) switches the sidebar to the Files pane and opens an inline create input at the root of the tree. Type a name and press Enter. The same input is available from the tree’s New note context-menu item, which creates the note inside the folder you right-clicked. The dashboard’s New note button does the same thing.

Escape

Escape is handled globally, and the first match in this order wins:

1. Close the command palette if it is open.
2. Close the settings modal if it is open.
3. Close quick open if it is open.
4. Close the active tab if it is a search tab.

If none of those apply, Escape falls through to whatever has focus. Modal dialogs handle their own Escape, and every modal traps focus while it is open, returning focus to wherever it came from on close.

The dashboard

Whenever no tab is active you see the dashboard: a greeting, the date and a clock that re-ticks every 30 seconds, and the vault name. It offers four quick actions, New note, Quick open, Search vault, and Command palette, plus lists of Recently modified and Recently closed notes.

Two quirks are worth knowing. The keyboard glyphs printed on those buttons are hardcoded macOS symbols, so a Windows or Linux machine still sees ⌘P, ⌘⇧F, and ⌘⇧P even though Ctrl is the key you press. And the dashboard’s Search vault button opens the sidebar search pane, while the identically named command in the palette opens the full search page. They are two different surfaces.

The right sidebar

The right sidebar is hidden when no vault is open and collapsed by default otherwise. It holds a Calendar pane and a Tasks pane, plus an Open history action that is disabled unless the active tab is a .md note.

One behavior to know before you click around: every cell in the calendar creates that day’s daily note when clicked, including the greyed-out days that belong to the previous or next month. Daily notes, task tracking, and templates are covered in Daily notes, tasks, and templates.

Where to go next

• The editor covers WYSIWYG editing, markdown input rules, the slash menu, tables, and source mode.
• Keyboard shortcuts is the complete chord reference.
• Search explains the two search surfaces and the keyword, semantic, and smart modes.
• Sync and sharing covers the encrypted sync setup, the recovery phrase, and sharing notes with other people.
• Settings reference documents every setting and its default.
• Troubleshooting is where to look when something behaves unexpectedly.
• Install and setup starts the CLI documentation, if you want to drive the same vault from a terminal or give an AI agent access to it.