Configuring Jotter

You can customize how Jotter operates (such as altering the network port or changing where your task files are stored) using command-line arguments, environment variables, or a configuration file.

---

Configuration Properties

Setting	CLI Option	Config File Key	Env Variable	Default Value	Description
Port	--port <number>	port: <number>	N/A	58271	The network port the server listens on.
Host	--host <address>	host: "<address>"	N/A	127.0.0.1	The host IP address to bind to (e.g. 0.0.0.0 to allow local network access).
Log Directory	N/A	log_dir: "<path>"	JOTTER_LOG_DIR	See Storage Locations	The directory where Jotter saves its jotter.log file. Separated from notes to avoid Git tracking conflicts.
Log Level	--log-level <level>	log_level: "<level>"	JOTTER_LOG_LEVEL	info (dev) / warning (prod)	Logging verbosity (debug, info, warning, error, critical).
Log Colors	--no-color	use_colors: false	NO_COLOR / JOTTER_USE_COLORS	true (auto)	Toggle ANSI colored terminal log output. Useful if legacy Windows terminals show escape codes ([32m).
Config File	--config <path> / -c	N/A	N/A	See Storage Locations	Specifies a custom YAML or JSON configuration file path. Automatically created if missing.

---

Storage Locations

Note: Vaults are managed in the app (gear icon next to the vault switcher) and stored in vaults.json in the config folder. The former data_dir config key, JOTTER_DATA_DIR environment variable and --data-dir option are no longer supported; the config key and environment variable are ignored with a warning.

A ./jotter.yaml (or ./jotter.yml/./jotter.json) in the Current Working Directory is read before the global configuration file. Only the first vault is created automatically, inside the config folder, and it never depends on the working directory.

Operating System	Default Vault	Default Configuration File	Default Log Directory
Linux	~/.config/jotter/tasks	~/.config/jotter/jotter.yaml	~/.cache/jotter
macOS	~/Library/Application Support/jotter/tasks	~/Library/Application Support/jotter/jotter.yaml	~/Library/Logs/Jotter
Windows	%APPDATA%\jotter\tasks	%APPDATA%\jotter\jotter.yaml	%LocalAppData%\Jotter

Note: Installs that already have a vaults.json keep the vault paths stored in it. If vaults.json cannot be read, Jotter stops with an error and leaves the file untouched instead of creating a new default vault.

---

Logging & Dual-Writer

Jotter employs a Dual-Writer Logging mechanism. This means that all log statements (starting up information, synchronization reports, git activities, and system errors) are output to both standard output (stdout) and appended to a persistent local log file named jotter.log.

This file is isolated from your markdown data directory so that it is never tracked by Jotter's Git auto-commits.

Log Rotation

To protect local disk space, Jotter automatically limits the size of the jotter.log file. On startup, if the file exceeds 5 MB, it is automatically removed and a clean log file is created.

---

Automatic Configuration Creation

To make initial setups completely effortless, if no configuration file exists at all, Jotter will automatically create a default, annotated configuration file in its default location (the Default Configuration File path above).

The created file contains template parameters that are commented out, serving as a ready-to-use template for your customizations:

# Jotter Configuration File
# log_dir: ""
# host: "127.0.0.1"
# port: 58271
# log_level: "INFO"

---

Configuration Priority Order

Jotter resolves settings using the following priority (highest overrides lowest):

1. Command Line Arguments (e.g. --port 9000)
2. Environment Variables (e.g. JOTTER_PORT)
3. Loaded Configuration File (jotter.yaml/jotter.yml/jotter.json)
4. Default Paths (OS standard directories)

---

Command Line Examples

• Run on a custom port:

  jotter --port 8080

• Use a specific config file in another location:

  jotter --config /etc/jotter/config.yaml

---

Git Versioning

If your vault folder is a Git repository, Jotter commits local changes to it automatically shortly after every change (at most once per minute), or whenever you click the Commit button in the sidebar footer. These commits power the Time Machine.

Jotter only ever commits locally. It creates a repository only when you click Enable Git, and it never pushes or pulls. See Git Versioning and Time Machine for details and for how to sync a vault across devices.