cli + tui to publish to leaflet (wip) & manage tasks, notes & watch/read lists 🍃
desertthunder.dev
charm
leaflet
readability
golang
1---
2id: configuration
3title: Configuration
4sidebar_label: Configuration
5sidebar_position: 6
6description: Reference for configuration locations, defaults, and options.
7---
8
9# Configuration
10
11Noteleaf stores its configuration in a TOML file. The configuration file location depends on your operating system and can be overridden with environment variables.
12
13## Configuration File Location
14
15### Default Paths
16
17**Linux:**
18
19```sh
20~/.config/noteleaf/.noteleaf.conf.toml
21```
22
23**macOS:**
24
25```sh
26~/Library/Application Support/noteleaf/.noteleaf.conf.toml
27```
28
29**Windows:**
30
31```sh
32%APPDATA%\noteleaf\.noteleaf.conf.toml
33```
34
35### Environment Variable Override
36
37Set `NOTELEAF_CONFIG` to use a custom configuration file location:
38
39```sh
40export NOTELEAF_CONFIG=/path/to/custom/config.toml
41```
42
43### File Structure
44
45Configuration is stored as [TOML](https://toml.io). Each key maps 1:1 with the fields shown by `noteleaf config show`. A minimal file looks like:
46
47```toml
48date_format = "2006-01-02"
49color_scheme = "default"
50```
51
52There is no required ordering—the parser loads the file, applies defaults for missing keys, and writes a normalized version whenever you run `noteleaf config set ...`. This means you can edit the file manually or stick entirely to CLI helpers.
53
54## Configuration Options
55
56### General Settings
57
58#### date_format
59
60Format for displaying dates throughout the application.
61
62**Type:** String
63**Default:** `"2006-01-02"` (ISO 8601)
64**Example:**
65
66```toml
67date_format = "2006-01-02"
68```
69
70Common formats:
71
72- `"2006-01-02"` - ISO format: 2024-03-15
73- `"01/02/2006"` - US format: 03/15/2024
74- `"02-Jan-2006"` - Short month: 15-Mar-2024
75
76#### color_scheme
77
78Color scheme for terminal output.
79
80**Type:** String
81**Default:** `"default"`
82**Example:**
83
84```toml
85color_scheme = "default"
86```
87
88#### default_view
89
90Default view mode for interactive lists.
91
92**Type:** String
93**Default:** `"list"`
94**Example:**
95
96```toml
97default_view = "list"
98```
99
100#### default_priority
101
102Default priority for new tasks when not specified.
103
104**Type:** String
105**Default:** None
106**Options:** `"low"`, `"medium"`, `"high"`, `"urgent"`
107**Example:**
108
109```toml
110default_priority = "medium"
111```
112
113#### editor
114
115Text editor for editing notes and tasks. Falls back to `$EDITOR` environment variable if not set.
116
117**Type:** String
118**Default:** None (uses `$EDITOR`)
119**Example:**
120
121```toml
122editor = "vim"
123```
124
125### Data Storage
126
127#### database_path
128
129Custom path to SQLite database file. Leave empty to use default location.
130
131**Type:** String
132**Default:** Platform-specific data directory
133**Example:**
134
135```toml
136database_path = "/custom/path/noteleaf.db"
137```
138
139#### data_dir
140
141Directory for storing application data (articles, notes, attachments).
142
143**Type:** String
144**Default:** Platform-specific data directory
145**Example:**
146
147```toml
148data_dir = "/custom/data/directory"
149```
150
151You can also use the `NOTELEAF_DATA_DIR` environment variable:
152
153```sh
154export NOTELEAF_DATA_DIR=/custom/data/directory
155```
156
157#### articles_dir
158
159Directory for storing saved articles.
160
161**Type:** String
162**Default:** `<data_dir>/articles`
163**Example:**
164
165```toml
166articles_dir = "/path/to/articles"
167```
168
169#### notes_dir
170
171Directory for storing notes.
172
173**Type:** String
174**Default:** `<data_dir>/notes`
175**Example:**
176
177```toml
178notes_dir = "/path/to/notes"
179```
180
181### Archive and Export
182
183#### auto_archive
184
185Automatically archive completed tasks after a specified period.
186
187**Type:** Boolean
188**Default:** `false`
189**Example:**
190
191```toml
192auto_archive = true
193```
194
195#### export_format
196
197Default format for exporting data.
198
199**Type:** String
200**Default:** `"json"`
201**Options:** `"json"`, `"csv"`, `"markdown"`
202**Example:**
203
204```toml
205export_format = "json"
206```
207
208### Synchronization
209
210Synchronization features are planned for future releases.
211
212#### sync_enabled
213
214Enable synchronization with remote server.
215
216**Type:** Boolean
217**Default:** `false`
218**Example:**
219
220```toml
221sync_enabled = false
222```
223
224#### sync_endpoint
225
226URL of the synchronization server.
227
228**Type:** String
229**Default:** None
230**Example:**
231
232```toml
233sync_endpoint = "https://sync.example.com/api"
234```
235
236#### sync_token
237
238Authentication token for synchronization.
239
240**Type:** String
241**Default:** None
242**Example:**
243
244```toml
245sync_token = "your-secret-token"
246```
247
248### API Keys
249
250#### movie_api_key
251
252API key for movie database services (future feature).
253
254**Type:** String
255**Default:** None
256**Example:**
257
258```toml
259movie_api_key = "your-api-key"
260```
261
262#### book_api_key
263
264API key for book database services. Currently uses Open Library which doesn't require an API key.
265
266**Type:** String
267**Default:** None
268**Example:**
269
270```toml
271book_api_key = "your-api-key"
272```
273
274### AT Protocol / Bluesky Integration
275
276Configuration for publishing content to Bluesky/AT Protocol.
277
278#### atproto_did
279
280Your Decentralized Identifier (DID) on the AT Protocol network.
281
282**Type:** String
283**Default:** None
284**Example:**
285
286```toml
287atproto_did = "did:plc:abcd1234efgh5678"
288```
289
290#### atproto_handle
291
292Your Bluesky/AT Protocol handle.
293
294**Type:** String
295**Default:** None
296**Example:**
297
298```toml
299atproto_handle = "username.bsky.social"
300```
301
302#### atproto_pds_url
303
304Personal Data Server URL.
305
306**Type:** String
307**Default:** None
308**Example:**
309
310```toml
311atproto_pds_url = "https://bsky.social"
312```
313
314#### atproto_access_jwt
315
316Access token for authentication (managed automatically).
317
318**Type:** String
319**Default:** None
320**Example:**
321
322```toml
323atproto_access_jwt = "eyJhbGc..."
324```
325
326#### atproto_refresh_jwt
327
328Refresh token for authentication (managed automatically).
329
330**Type:** String
331**Default:** None
332
333#### atproto_expires_at
334
335Token expiration timestamp (managed automatically).
336
337**Type:** String (ISO8601)
338**Default:** None
339
340## Editor Integration
341
342The `editor` key wires Noteleaf into your preferred text editor. Resolution order:
343
3441. `editor` inside `.noteleaf.conf.toml`
3452. `$EDITOR` environment variable
3463. System default (usually `vi` on Unix)
347
348Where it is used:
349
350- `noteleaf note edit <id>` always opens the configured editor.
351- `noteleaf note create -e` or `--editor` lets you capture inline text and immediately refine it in the editor.
352- Interactive creation (`noteleaf note create -i`) respects the same setting when you choose to open the note.
353
354Example configuration:
355
356```toml
357editor = "nvim"
358```
359
360If you frequently switch editors, leave the config empty and export `$EDITOR` before launching Noteleaf:
361
362```sh
363EDITOR="zed" noteleaf note edit 5
364```
365
366## Managing Configuration
367
368### View Current Configuration
369
370```sh
371noteleaf config show
372```
373
374### Set Configuration Value
375
376```sh
377noteleaf config set <key> <value>
378```
379
380Examples:
381
382```sh
383noteleaf config set editor "nvim"
384noteleaf config set default_priority "high"
385noteleaf config set date_format "01/02/2006"
386```
387
388### Get Configuration Value
389
390```sh
391noteleaf config get <key>
392```
393
394Example:
395
396```sh
397noteleaf config get editor
398```
399
400## Example Configuration
401
402Complete example configuration with common settings:
403
404```toml
405# General settings
406date_format = "2006-01-02"
407color_scheme = "default"
408default_view = "list"
409default_priority = "medium"
410editor = "vim"
411
412# Data storage
413# database_path = "" # Use default location
414# data_dir = "" # Use default location
415
416# Archive and export
417auto_archive = false
418export_format = "json"
419
420# Synchronization (future feature)
421sync_enabled = false
422# sync_endpoint = ""
423# sync_token = ""
424
425# API keys (optional)
426# movie_api_key = ""
427# book_api_key = ""
428
429# AT Protocol / Bluesky (optional)
430# atproto_did = ""
431# atproto_handle = ""
432# atproto_pds_url = "https://bsky.social"
433```
434
435## Environment Variables
436
437Environment overrides are resolved before configuration values. Set them when you need temporary behavior (CI jobs, alternate workspaces, etc.).
438
439| Variable | Purpose | Notes |
440|----------|---------|-------|
441| `NOTELEAF_CONFIG` | Absolute path to the TOML file | Overrides platform defaults. Parent directories are created automatically. |
442| `NOTELEAF_DATA_DIR` | Root directory for the SQLite DB, notes, articles, and attachments | Useful for portable installs (USB drive, synced folder). |
443| `EDITOR` | Fallback editor when the `editor` config key is empty | Checked by all note-related commands. |
444
445Usage example:
446
447```sh
448export NOTELEAF_CONFIG=~/.config/noteleaf/work.conf.toml
449export NOTELEAF_DATA_DIR=~/Sync/workspace-data
450export EDITOR=helix
451```
452
453Because `NOTELEAF_DATA_DIR` cascades to the article and note directories, a single export is all you need to relocate the entire knowledge base.
454
455## Customization
456
457### Themes and Colors
458
459The `color_scheme` option controls how Fang (the underlying Cobra replacement) styles command help and certain UI components. Right now the only valid value is `"default"`, which maps to Noteleaf’s Iceberg-inspired palette. Future releases will add explicit `light`/`dark` options; until then customization requires overriding your terminal theme or building Noteleaf from source with changes in `internal/ui/palette.go`.
460
461```toml
462color_scheme = "default" # leave blank to adopt upcoming auto-mode
463```
464
465### Keyboard Shortcuts
466
467All interactive views share the same key map:
468
469| Keys | Action |
470|------|--------|
471| `↑ / k`, `↓ / j` | Move selection |
472| `enter` | Open the selected row |
473| `v` | View details in a side panel (where supported) |
474| `/` | Search/filter (live) |
475| `r` | Reload data |
476| `?` | Show full help, including custom actions for the current view |
477| `q`, `ctrl+c` | Quit the view |
478| `esc`, `backspace` | Exit search/help/detail panels |
479| `1-9` | Jump directly to the corresponding row index |
480
481Press `?` inside any list/table to confirm the bindings—this uses Bubble Tea’s built-in help component so it always reflects the current screen.
482
483### Output Formats
484
485- `export_format` sets the default for future export commands (currently `json`).
486- Task commands support JSON today: `noteleaf todo view 12 --json` or `noteleaf todo list --static --json`.
487- The `--format` flag on `noteleaf todo view` switches between `detailed` and `brief` layouts, which is handy when scripting.
488
489Examples:
490
491```sh
492noteleaf todo view 12 --format brief --json | jq '.status'
493noteleaf todo list --static --json > tasks.json
494noteleaf config set export_format "csv" # prepare for upcoming exporters
495```
496
497Even when there is no dedicated exporter yet, the SQLite database lives in the open, so you can always run your own `SELECT ...` queries or use `sqlite-utils` to produce CSV/JSON.