# Habits

Track habits in plain notes: check off a day, read your streaks, and set a color or icon for each habit, in the app or the CLI.

A habit is a note in the `Habits` folder. Each day you do it is one line, `- [x] YYYY-MM-DD`. Loam counts your current and longest streak from those lines. The folder is `Habits` by default, and you can change it in the Habit tracker settings.

## Create a habit

The name cannot be empty, contain `/`, or start with a dot. The command fails if the habit already exists.

```bash
loam --vault ~/Notes habits.create name=Meditate
```

The note gets a `created` date and a `## Check-ins` section. After two check-ins, it looks like this:

```markdown
---
created: 2026-10-28
---
# Meditate

## Check-ins
- [x] 2026-10-28
- [x] 2026-10-27
```

## Check off a day

Without a `date`, the check-in is for today. Checking a day twice changes nothing.

```bash
loam --vault ~/Notes habits.check name=Meditate
loam --vault ~/Notes habits.check name=Meditate date=2026-10-27
loam --vault ~/Notes habits.uncheck name=Meditate date=2026-10-27
loam --vault ~/Notes habits.status name=Meditate
```

`habits.status` returns the check-ins, the current streak and the longest streak. In the app, the habits board shows every habit over the last one to four weeks, depending on the width of the window. Click a day to check it.

## Set a color or icon, or archive a habit

Use `habits.set` with `key` set to `color`, `icon` or `archived`. Pass an empty `value` to remove the property. Colors are names such as `orange` or `blue`. Archived habits stay in the note, but leave the board.

```bash
loam --vault ~/Notes habits.set name=Meditate key=color value=orange
loam --vault ~/Notes habits.set name=Meditate key=icon value="🧘"
loam --vault ~/Notes habits.set name=Meditate key=archived value=true
```

## Commands

| Command | Arguments | What it does |
| --- | --- | --- |
| habits.create | name | Creates the habit's note and returns its path. |
| habits.list | none | Lists the status of every habit in the folder. |
| habits.check | name, date (optional) | Records a day. Without a date, it is today. |
| habits.uncheck | name, date (optional) | Removes a day from the check-ins, and returns the new status. |
| habits.status | name | Returns the check-ins and the current and longest streaks. |
| habits.set | name, key (color, icon or archived), value | Sets a property of the habit's note. An empty value removes it. |

> **Tip:** For AI agents: `loam list` shows the `habits.*` commands with their arguments.