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
44- Using [bin](https://github.com/marcosnils/bin) (recommended to
45 centralise and automate updating of binaries/CLI tools like this, but
46 still requires the Go toolchain):
47 ```bash
48 bin install goinstall://git.secluded.site/lune@latest
49 ```
50- Using the [Go toolchain](https://go.dev/dl) without bin (requires
51 tracking updates manually):
52 ```bash
53 go install git.secluded.site/lune@latest
54 ```
55
56Then run `lune init` to configure your access token and copy areas,
57goals, notebooks, and habits from the Lunatask desktop app.
58
59## Usage
60
61### Shortcuts
62
63Quick commands for the most common actions:
64
65| Command | Description |
66| ---------------- | ---------------------------------- |
67| `lune add NAME` | Create task (alias for `task add`) |
68| `lune done ID` | Mark task completed |
69| `lune jrnl TEXT` | Add journal entry |
70
71### Resources
72
73Full CRUD for Lunatask resources:
74
75```bash
76# Tasks
77lune task add "Name" -a AREA -g GOAL -s STATUS -n "note" -p PRIORITY
78lune task list [-a AREA] [-s STATUS] [--all] [--json]
79lune task show ID [--json]
80lune task update ID [-s STATUS] [--name "new name"] [--schedule "tomorrow"]
81lune task delete ID [-f]
82
83# Notes
84lune note add "Title" -b NOTEBOOK -c "content"
85lune note list [-b NOTEBOOK] [--json]
86lune note show ID [--json]
87lune note update ID [-c "new content"]
88lune note delete ID [-f]
89
90# Journal
91lune journal add [CONTENT] [-d DATE] [-n NAME]
92
93# Habits
94lune habit track KEY [-d DATE]
95
96# People (relationship tracker)
97lune person add FIRST LAST [-r RELATIONSHIP]
98lune person list [--json]
99lune person show ID [--json]
100lune person timeline ID -c "Met for coffee" [-d DATE]
101lune person update ID [-r RELATIONSHIP]
102lune person delete ID [-f]
103
104# Config inspection
105lune area list [--json]
106lune area show KEY [--json]
107lune goal list [-a AREA] [--all] [--json]
108lune goal show KEY [--json]
109```
110
111### Flag reference
112
113**Task flags:**
114
115- `-a, --area` — area key from config
116- `-g, --goal` — goal key (requires area)
117- `-s, --status` — later, next, in-progress, waiting, completed
118- `-n, --note` — task note (use `-` for stdin)
119- `-p, --priority` — lowest, low, normal, high, highest
120- `-e, --estimate` — time estimate in minutes (0-720)
121- `-m, --motivation` — must, should, want
122- `--important`, `--not-important` — Eisenhower matrix
123- `--urgent`, `--not-urgent` — Eisenhower matrix
124- `--schedule` — scheduled date (natural language)
125
126**Habit flags:**
127
128- `-d, --date` — date performed (default: today)
129
130**Journal flags:**
131
132- `-d, --date` — entry date (default: today)
133- `-n, --name` — entry title (default: weekday name)
134
135**Person flags:**
136
137- `-r, --relationship` — family, intimate-friends, close-friends,
138 casual-friends, acquaintances, business-contacts, almost-strangers
139
140### Stdin support
141
142Read content from stdin using `-`:
143
144```bash
145# Task name from stdin
146echo "Review quarterly report" | lune add -
147
148# Note content from stdin
149cat meeting-notes.md | lune note add "Meeting Notes" -b work -c -
150
151# Journal entry from stdin
152echo "Wrapped up the project" | lune jrnl -
153```
154
155### Configuration
156
157Config lives at `~/.config/lune/config.toml`. Run `lune init` anytime to
158modify it through the interactive wizard, or edit directly:
159
160```toml
161[ui]
162color = "auto" # "always", "never", or "auto"
163
164[defaults]
165area = "work"
166notebook = "notes"
167
168[[areas]]
169id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
170name = "Work"
171key = "work"
172
173 [[areas.goals]]
174 id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
175 name = "Q1 Goals"
176 key = "q1"
177
178[[notebooks]]
179id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
180name = "Work Notes"
181key = "notes"
182
183[[habits]]
184id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
185name = "Meditation"
186key = "meditation"
187```
188
189**Where to find IDs:** In the Lunatask desktop app, open any item's settings
190modal and click "Copy [Item] ID" in the bottom left.
191
192## A note on end-to-end encryption
193
194Lunatask is end-to-end encrypted, which means lune can only access metadata
195(IDs, timestamps, status, etc.)—not the names or contents of your tasks, notes,
196habits, etc. This is by design. When listing items, you'll see IDs and dates
197but not titles.
198
199Creating items works because you provide the plain content and the desktop app
200encrypts it. The API can't decrypt anything so it can't read encrypted content
201back to you.
202
203## Contributions
204
205Patch requests are in [amolith/lune](https://pr.pico.sh/r/amolith/lune) on
206[pr.pico.sh](https://pr.pico.sh). You don't need a new account to contribute,
207you don't need to fork this repo, you don't need to fiddle with `git
208send-email`, you don't need to faff with your email client to get `git
209request-pull` working...
210
211You just need:
212
213- Git
214- SSH
215- An SSH key
216
217```bash
218# Clone this repo, make your changes, and commit them
219# Create a new patch request with
220git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/lune
221# After potential feedback, submit a revision to an existing patch request with
222git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
223# List patch requests
224ssh pr.pico.sh pr ls amolith/lune
225```
226
227See "How do Patch Requests work?" on [pr.pico.sh](https://pr.pico.sh)'s home
228page for a more complete example workflow.
229
230---
231
232Some other tools if this one interested you:
233
234- [go-lunatask](https://git.secluded.site/go-lunatask) — the Go client library
235 lune is built with
236- [lunatask-mcp-server](https://git.secluded.site/lunatask-mcp-server) — MCP
237 server for interacting with Lunatask via LLMs