1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# lune
8
9[](https://api.reuse.software/info/git.secluded.site/lune)
10[](https://goreportcard.com/report/git.secluded.site/lune)
11[](https://liberapay.com/Amolith/)
12
13Lune (/lyn/, French for "moon" and rhymes with it) is a delightful CLI
14for [Lunatask](https://lunatask.app).
15
16## tl;dr
17
18```bash
19lune init # Interactive setup wizard
20lune add "Review PR" -a work -s next # Create task in work area
21lune done ID # Mark task completed
22lune jrnl "Productive day!" # Quick journal entry
23lune habit track meditation # Track a habit
24```
25
26## Features
27
28- **Interactive setup** — guided wizard configures areas, goals,
29 notebooks, habits, and your access token
30- **Secure storage** — access token lives in the system keyring, not a
31 file
32- **Natural language dates** — "yesterday", "-2 days", "next Monday" all
33 work
34- **Deep link support** — paste `lunatask://` URLs or plain IDs
35- **Stdin-friendly** — use `-` to pipe content into tasks, notes, and
36 journal entries
37- **Shell completion** — tab-complete areas, goals, notebooks, and
38 habits
39- **JSON output** — most commands support `--json` for scripting
40- **Config keys** — use short aliases like `work` instead of UUIDs
41
42## Installation
43
44Pre-built binaries are available at
45[releases.secluded.site/lune/latest][bin-latest].
46
47[bin-latest]: https://releases.secluded.site/lune/latest
48
49- Using [mise](https://mise.jdx.dev/) (recommended), copy the snippet from the
50 releases page into your `mise.toml` or global `~/.config/mise/config.toml` to
51 automate updates.
52- Without mise, or a similar tool, download the binary for your platform from
53 the releases page and place it somewhere in your `$PATH`.
54
55Then run `lune init` to configure your access token and copy areas,
56goals, notebooks, and habits from the Lunatask desktop app.
57
58## Usage
59
60### Shortcuts
61
62Quick commands for the most common actions:
63
64| Command | Description |
65| ---------------- | ---------------------------------- |
66| `lune add NAME` | Create task (alias for `task add`) |
67| `lune done ID` | Mark task completed |
68| `lune jrnl TEXT` | Add journal entry |
69
70### Resources
71
72Full CRUD for Lunatask resources:
73
74```bash
75# Tasks
76lune task add "Name" -a AREA -g GOAL -s STATUS -n "note" -p PRIORITY
77lune task list [-a AREA] [-s STATUS] [--all] [--json]
78lune task show ID [--json]
79lune task update ID [-s STATUS] [--name "new name"] [--schedule "tomorrow"]
80lune task delete ID [-f]
81
82# Notes
83lune note add "Title" -b NOTEBOOK -c "content"
84lune note list [-b NOTEBOOK] [--json]
85lune note show ID [--json]
86lune note update ID [-c "new content"]
87lune note delete ID [-f]
88
89# Journal
90lune journal add [CONTENT] [-d DATE] [-n NAME]
91
92# Habits
93lune habit track KEY [-d DATE]
94
95# People (relationship tracker)
96lune person add FIRST LAST [-r RELATIONSHIP]
97lune person list [--json]
98lune person show ID [--json]
99lune person timeline ID -c "Met for coffee" [-d DATE]
100lune person update ID [-r RELATIONSHIP]
101lune person delete ID [-f]
102
103# Config inspection
104lune area list [--json]
105lune area show KEY [--json]
106lune goal list [-a AREA] [--all] [--json]
107lune goal show KEY [--json]
108```
109
110### Flag reference
111
112**Task flags:**
113
114- `-a, --area` — area key from config
115- `-g, --goal` — goal key (requires area)
116- `-s, --status` — later, next, in-progress, waiting, completed
117- `-n, --note` — task note (use `-` for stdin)
118- `-p, --priority` — lowest, low, normal, high, highest
119- `-e, --estimate` — time estimate in minutes (0-720)
120- `-m, --motivation` — must, should, want
121- `--important`, `--not-important` — Eisenhower matrix
122- `--urgent`, `--not-urgent` — Eisenhower matrix
123- `--schedule` — scheduled date (natural language)
124
125**Habit flags:**
126
127- `-d, --date` — date performed (default: today)
128
129**Journal flags:**
130
131- `-d, --date` — entry date (default: today)
132- `-n, --name` — entry title (default: weekday name)
133
134**Person flags:**
135
136- `-r, --relationship` — family, intimate-friends, close-friends,
137 casual-friends, acquaintances, business-contacts, almost-strangers
138
139### Stdin support
140
141Read content from stdin using `-`:
142
143```bash
144# Task name from stdin
145echo "Review quarterly report" | lune add -
146
147# Note content from stdin
148cat meeting-notes.md | lune note add "Meeting Notes" -b work -c -
149
150# Journal entry from stdin
151echo "Wrapped up the project" | lune jrnl -
152```
153
154### Configuration
155
156Config lives at `~/.config/lune/config.toml`. Run `lune init` anytime to
157modify it through the interactive wizard, or edit directly:
158
159```toml
160[ui]
161color = "auto" # "always", "never", or "auto"
162
163[defaults]
164area = "work"
165notebook = "notes"
166
167[[areas]]
168id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
169name = "Work"
170key = "work"
171
172 [[areas.goals]]
173 id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
174 name = "Q1 Goals"
175 key = "q1"
176
177[[notebooks]]
178id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
179name = "Work Notes"
180key = "notes"
181
182[[habits]]
183id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
184name = "Meditation"
185key = "meditation"
186```
187
188**Where to find IDs:** In the Lunatask desktop app, open any item's settings
189modal and click "Copy [Item] ID" in the bottom left.
190
191## A note on end-to-end encryption
192
193Lunatask is end-to-end encrypted, which means lune can only access metadata
194(IDs, timestamps, status, etc.)—not the names or contents of your tasks, notes,
195habits, etc. This is by design. When listing items, you'll see IDs and dates
196but not titles.
197
198Creating items works because you provide the plain content and the desktop app
199encrypts it. The API can't decrypt anything so it can't read encrypted content
200back to you.
201
202## Contributions
203
204Patch requests are in [amolith/lune](https://pr.pico.sh/r/amolith/lune) on
205[pr.pico.sh](https://pr.pico.sh). You don't need a new account to contribute,
206you don't need to fork this repo, you don't need to fiddle with `git
207send-email`, you don't need to faff with your email client to get `git
208request-pull` working...
209
210You just need:
211
212- Git
213- SSH
214- An SSH key
215
216```bash
217# Clone this repo, make your changes, and commit them
218# Create a new patch request with
219git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/lune
220# After potential feedback, submit a revision to an existing patch request with
221git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
222# List patch requests
223ssh pr.pico.sh pr ls amolith/lune
224```
225
226See "How do Patch Requests work?" on [pr.pico.sh](https://pr.pico.sh)'s home
227page for a more complete example workflow.
228
229---
230
231Some other tools if this one interested you:
232
233- [go-lunatask](https://git.secluded.site/go-lunatask) — the Go client library lune is built with
234- [agent-skills](https://git.secluded.site/agent-skills) — collection of Agent Skills for extending LLM capabilities
235- [git-format](https://git.secluded.site/git-format) — CLI that turns LLM input into well-formatted conventional commits and tags