diario-cli 1.0.1.post4
Diario is an opinionated personal journaling tool inspired by bullet journal practices, based on plain UTF-8 Markdown files organized in a time-based directory structure. It prioritizes long-term readability, filesystem portability, and independence from the application itself.
Requires Python: <4.0,>=3.11

# Diario

A personal diary application inspired by the [bullet journal](https://bulletjournal.com) method.

Diario is a framework that is easy for humans to adopt 
and stick with, and easy for machines to process.  
It is also a strongly opinionated application: decisions 
about structure, format, and time subdivision are intentional 
and not configurable.  
What *is* configurable are the Markdown template files located 
in the `templates` directory.

The application was created to address the following needs:

* I wanted a personal note management system organized by days, weeks, months, quarters, and years.
* I wanted a system that is maintainable over the long term, ideally for the entire lifetime of the user.
* I wanted the application data not to depend on the application itself. Even if the app stopped working or was no longer maintained, all documents would remain readable, editable, and usable as simple Markdown files organized in directories.
* I wanted a system for which creating a backup is trivial. In this specific case, it is enough to copy a single directory.
* I wanted a system compatible with common cloud storage services (Dropbox, iCloud, Google Drive, …) and efficiently versionable with Git.
* I wanted a system simple enough to be used directly with a plain text editor.
* I wanted daily files to automatically reference weekly files, weekly files to reference monthly files, and so on.
* I wanted everything to be based on nested directories and simple UTF-8 encoded text files, to ensure that the data will still be easily readable and writable even 20 years from now.
* I wanted to use Markdown as the file format, so that writing could be done in plain text while still allowing some basic structure and formatting. Markdown is ideal because it represents an approach to expressing style in plain text, rather than being a full document format.
* I wanted all Markdown files to be manually editable at any time using any text editor.
* I wanted everything inside each subdirectory—except the `_index.md` file—to be implicitly treated as an attachment to the corresponding day, week, month, quarter, or year document.
* I wanted to rely only on functions available in the Python standard library (>= 3.11), in order to ensure maximum compatibility and long-term maintainability.

## Time subdivision

Time is subdivided into days, weeks, months, quarters, and years according to the ISO 8601 standard, which defines the week as starting on Monday and ending on Sunday.

* Daily: `{destination}/diary/daily/YYYY/MM/DD/`
* Weekly: `{destination}/diary/weekly/YYYY/WW/`
* Monthly: `{destination}/diary/monthly/YYYY/MM/`
* Quarterly: `{destination}/diary/quarterly/YYYY/QQ/`
* Yearly: `{destination}/diary/yearly/YYYY/`

> Note 1: `WW` is a number from 01 to 53 representing the ISO 8601 week number.  
> Note 2: `QQ` is a number from 01 to 04 representing the quarter.

## Installation

The application can be installed using `pipx` by running the following command:

```
pipx install diario-cli
```

The application expects a configuration file named `config.json` to exist inside the `~/.config/diario/` directory. If the file, the directory, or both do not exist, they will be created automatically with default settings.

Both the destination directory and the default text editor can be changed by editing the configuration file located at `~/.config/diario/config.json`.

These are the default configuration parameters:

```json
{
  "path": "~/.local/share/diario",
  "locale": "en_US",
  "editor": "nano"
}
```

The `editor` parameter can be either a string or a list of strings, for example: `["open", "-a", "/Applications/MarkEdit.app/Contents/MacOS/MarkEdit"]`

## Usage

To start the application and create a document for the current day, run:

```
diario
```

After running the command, the application will create all required documents and invoke the text editor defined in the configuration file. By default, the application will attempt to use the `nano` editor.

To create a document for a specific day, run:

```
diario 24-12-2027
```

To create a document for the day after the current one, run:

```
diario --tomorrow
```

To automatically create all documents starting from today and covering the next 365 days, run:

```
diario --populate
```

For additional options, refer to the built-in help:

```
diario --help
```

## Frequently asked questions

### "But I have to rewrite every task I have in my calendar, each time between daily, weekly and monthly documents!"

Some tasks will appear in multiple places.
**This is absolutely intentional.**
As highlighted by the *Bullet Journal* method, rewriting is part of the review process, not an inefficiency.  

Think about it this way:  
**If a task is not worth rewriting, it may not be worth carrying forward.**

## Example directory structure created by the application

```
~/.local/share/diario/
├── diary
│   ├── daily
│   │   ├── 2026
│   │   │   ├── 01
│   │   │   │   ├── 25
│   │   │   │   │   └── _index.md
│   │   │   │   ├── 26
│   │   │   │   │   └── _index.md
│   │   │   │   ├── 27
│   │   │   │   │   └── _index.md
│   │   │   │   ├── 28
│   │   │   │   │   └── _index.md
│   │   │   │   ├── 29
│   │   │   │   │   └── _index.md
│   │   │   │   ├── 30
│   │   │   │   │   └── _index.md
│   │   │   │   └── 31
│   │   │   │       └── _index.md
│   │   │   ├── 02
│   │   │   │   ├── 01
│   │   │   │   │   └── _index.md
│   │   │   │   ├── 02
│   │   │   │   │   └── _index.md
.   .   .   .   .   .
│   ├── monthly
│   │   ├── 2026
│   │   │   ├── 01
│   │   │   │   └── _index.md
│   │   │   ├── 02
│   │   │   │   └── _index.md
│   │   │   ├── 03
│   │   │   │   └── _index.md
│   │   │   ├── 04
│   │   │   │   └── _index.md
│   │   │   ├── 05
│   │   │   │   └── _index.md
│   │   │   ├── 06
│   │   │   │   └── _index.md
│   │   │   ├── 07
│   │   │   │   └── _index.md
│   │   │   ├── 08
│   │   │   │   └── _index.md
│   │   │   ├── 09
│   │   │   │   └── _index.md
│   │   │   ├── 10
│   │   │   │   └── _index.md
│   │   │   ├── 11
│   │   │   │   └── _index.md
│   │   │   └── 12
│   │   │       └── _index.md
.   .   .
│   ├── quarterly
│   │   ├── 2026
│   │   │   ├── 01
│   │   │   │   └── _index.md
│   │   │   ├── 02
│   │   │   │   └── _index.md
│   │   │   ├── 03
│   │   │   │   └── _index.md
│   │   │   └── 04
│   │   │       └── _index.md
.   .   .
│   ├── weekly
│   │   ├── 2026
│   │   │   ├── 04
│   │   │   │   └── _index.md
│   │   │   ├── 05
│   │   │   │   └── _index.md
│   │   │   ├── 06
│   │   │   │   └── _index.md
│   │   │   ├── 07
.   .   .   .
│   └── yearly
│       ├── 2026
│       │   └── _index.md
└── templates
    ├── daily.md
    ├── monthly.md
    ├── quarterly.md
    ├── weekly.md
    └── yearly.md
```