taskli-cli 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. taskli_cli-1.0.0/.gitignore +61 -0
  2. taskli_cli-1.0.0/CHANGELOG.md +88 -0
  3. taskli_cli-1.0.0/LICENSE +21 -0
  4. taskli_cli-1.0.0/PKG-INFO +208 -0
  5. taskli_cli-1.0.0/README.md +180 -0
  6. taskli_cli-1.0.0/completions/README.md +34 -0
  7. taskli_cli-1.0.0/completions/taskli.ps1 +38 -0
  8. taskli_cli-1.0.0/completions/taskli.sh +81 -0
  9. taskli_cli-1.0.0/docs/assets/agenda.svg +100 -0
  10. taskli_cli-1.0.0/docs/assets/details.svg +136 -0
  11. taskli_cli-1.0.0/docs/assets/filter.svg +107 -0
  12. taskli_cli-1.0.0/docs/assets/hero.svg +135 -0
  13. taskli_cli-1.0.0/docs/assets/lists.svg +73 -0
  14. taskli_cli-1.0.0/docs/assets/quickstart.svg +220 -0
  15. taskli_cli-1.0.0/docs/assets/states.svg +146 -0
  16. taskli_cli-1.0.0/docs/completion.md +58 -0
  17. taskli_cli-1.0.0/docs/config.md +47 -0
  18. taskli_cli-1.0.0/docs/lists.md +92 -0
  19. taskli_cli-1.0.0/docs/reference.md +136 -0
  20. taskli_cli-1.0.0/docs/stability.md +38 -0
  21. taskli_cli-1.0.0/docs/tasks.md +129 -0
  22. taskli_cli-1.0.0/pyproject.toml +181 -0
  23. taskli_cli-1.0.0/src/taskli/__init__.py +0 -0
  24. taskli_cli-1.0.0/src/taskli/__version__.py +6 -0
  25. taskli_cli-1.0.0/src/taskli/cli.py +1073 -0
  26. taskli_cli-1.0.0/src/taskli/env.py +44 -0
  27. taskli_cli-1.0.0/src/taskli/exceptions.py +74 -0
  28. taskli_cli-1.0.0/src/taskli/hierarchy.py +88 -0
  29. taskli_cli-1.0.0/src/taskli/logic.py +1099 -0
  30. taskli_cli-1.0.0/src/taskli/migrations.py +165 -0
  31. taskli_cli-1.0.0/src/taskli/models/__init__.py +1 -0
  32. taskli_cli-1.0.0/src/taskli/models/attributes.py +140 -0
  33. taskli_cli-1.0.0/src/taskli/models/config.py +111 -0
  34. taskli_cli-1.0.0/src/taskli/models/dates.py +141 -0
  35. taskli_cli-1.0.0/src/taskli/models/paths.py +21 -0
  36. taskli_cli-1.0.0/src/taskli/models/query.py +250 -0
  37. taskli_cli-1.0.0/src/taskli/models/registry.py +215 -0
  38. taskli_cli-1.0.0/src/taskli/models/tasks.py +764 -0
  39. taskli_cli-1.0.0/src/taskli/py.typed +0 -0
  40. taskli_cli-1.0.0/src/taskli/render.py +520 -0
  41. taskli_cli-1.0.0/src/taskli/storage.py +687 -0
  42. taskli_cli-1.0.0/tests/conftest.py +8 -0
  43. taskli_cli-1.0.0/tests/resources/config_v0_legacy.json +8 -0
  44. taskli_cli-1.0.0/tests/resources/config_v1.json +9 -0
  45. taskli_cli-1.0.0/tests/resources/list_v0_legacy.json +26 -0
  46. taskli_cli-1.0.0/tests/resources/list_v1.json +54 -0
  47. taskli_cli-1.0.0/tests/test_completions.py +96 -0
  48. taskli_cli-1.0.0/tests/unit/test_cli.py +2610 -0
  49. taskli_cli-1.0.0/tests/unit/test_dates.py +142 -0
  50. taskli_cli-1.0.0/tests/unit/test_env.py +44 -0
  51. taskli_cli-1.0.0/tests/unit/test_hierarchy.py +56 -0
  52. taskli_cli-1.0.0/tests/unit/test_logic.py +876 -0
  53. taskli_cli-1.0.0/tests/unit/test_migrations.py +159 -0
  54. taskli_cli-1.0.0/tests/unit/test_models.py +1168 -0
  55. taskli_cli-1.0.0/tests/unit/test_query.py +430 -0
  56. taskli_cli-1.0.0/tests/unit/test_registry.py +259 -0
  57. taskli_cli-1.0.0/tests/unit/test_render.py +427 -0
  58. taskli_cli-1.0.0/tests/unit/test_storage.py +618 -0
  59. taskli_cli-1.0.0/tests/utils.py +219 -0
@@ -0,0 +1,61 @@
1
+ # caches.
2
+ __pycache__/
3
+ .pytest_cache/
4
+ .cache
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+
8
+ # test things & artifacts.
9
+ htmlcov/
10
+ .coverage
11
+ .coverage.*
12
+ nosetests.xml
13
+ coverage.xml
14
+ *.cover
15
+ .hypothesis/
16
+ junit.xml
17
+ *.ipynb
18
+
19
+ # build.
20
+ *.so
21
+ .Python
22
+ build/
23
+ develop-eggs/
24
+ dist/
25
+ downloads/
26
+ eggs/
27
+ .eggs/
28
+ lib/
29
+ lib64/
30
+ parts/
31
+ sdist/
32
+ var/
33
+ wheels/
34
+ *.egg-info/
35
+ .installed.cfg
36
+ *.egg
37
+ .hatch*
38
+
39
+ # type checking.
40
+ .dmypy.json
41
+ dmypy.json
42
+
43
+ # IDE/machine config files.
44
+ .vscode/
45
+ .idea/
46
+ *.swp
47
+ *.DS_Store
48
+ *.db
49
+
50
+ # envs.
51
+ .env
52
+ *venv*/
53
+ *env*/
54
+
55
+ # issue-gated workflow runtime state.
56
+ .claude/.current-issue
57
+ .claude/.last-check
58
+ .claude/.pr-body.md
59
+ .claude/.doc-drift-ack
60
+ .claude/worktrees/
61
+ .claude/hooks/__pycache__/
@@ -0,0 +1,88 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [1.0.0] - 2026-11-05
11
+ <!-- set the real release date when merging -->
12
+
13
+ 1.0 begins the [stability promise](docs/stability.md): the CLI flag grammar and
14
+ the on-disk schema stay compatible across 1.x.
15
+
16
+ ### Added
17
+
18
+ - First release on PyPI as `taskli-cli`: `uv tool install taskli-cli` or
19
+ `pipx install taskli-cli`. The `tk` and `taskli` commands are unchanged.
20
+ - Nested subtasks at any depth, addressed by dotted ids (`1.2.1`) and created
21
+ with `--under`. `-e --under` re-nests an existing item; `--under ""` moves it
22
+ back to the top level.
23
+ - Due dates: `today`, `tomorrow`, `next-week`, `N days`, `N weeks`, weekday
24
+ names, and `MM-DD-YYYY`. Filter with `--today`, a repeatable `--due` (OR),
25
+ and `--due none` / `--undated`.
26
+ - `tk --agenda`: one cross-list timeline with a Priority column, a
27
+ configurable window (`agenda_window`), and `agenda_include_overdue`.
28
+ - A due/overdue reminder banner above commands, controlled by
29
+ `show_reminders`.
30
+ - `-D` / `--details` shows one task in full: description, timestamps, subtasks.
31
+ - Task descriptions (`--desc`), flagged with a `¶` in tables.
32
+ - `-d`, `-i`, `-u`, and `-rm` can be combined in one call.
33
+ - Sublists inherit their parent list's color (`inherit_sublist_color`).
34
+ - `silent_prune` config option to print only the `--prune` summary.
35
+ - Schema versioning for list and config files, and `tk --migrate` to upgrade
36
+ them.
37
+ - Checked-in shell completion scripts for bash, zsh, and PowerShell, and faster
38
+ tab completion.
39
+
40
+ ### Changed
41
+
42
+ - **Breaking vs 0.3.0-beta:** list and config files written by 0.3.0-beta must
43
+ be upgraded once with `tk --migrate`. taskli errors and points to it rather
44
+ than rewriting files itself.
45
+ - Requires Python 3.12 or newer.
46
+ - Item tables fold the ID, state, and text columns into a single `Task` column.
47
+ - `uv tool install` is now the recommended install path.
48
+
49
+ ## [0.3.0-beta] - 2026-08-12
50
+
51
+ ### Added
52
+
53
+ - Move and copy items between lists.
54
+ - Several modifiers in one command, and per-item tags and priority when adding
55
+ multiple items.
56
+ - A `modified_at` timestamp on items.
57
+ - `tk --version` and `tk --path`.
58
+ - The default list is shown in bold in `--lists`.
59
+
60
+ ### Changed
61
+
62
+ - **Breaking:** the command-line grammar was rewritten so every action is a
63
+ flag.
64
+ - Item ids follow the list's sort order.
65
+
66
+ ## [0.2.0-beta] - 2026-08-03
67
+
68
+ ### Added
69
+
70
+ - A user config file, managed with `--config`.
71
+ - A test suite with coverage reporting.
72
+
73
+ ### Changed
74
+
75
+ - Subparsers were replaced with plain arguments.
76
+ - Models were renamed to `Taskli*`, and `todo` became `task`.
77
+
78
+ ## [0.1.0-beta] - 2026-07-31
79
+
80
+ ### Added
81
+
82
+ - Initial release.
83
+
84
+ [Unreleased]: https://github.com/calvinmcelvain/taskli/compare/v1.0.0...HEAD
85
+ [1.0.0]: https://github.com/calvinmcelvain/taskli/compare/v0.3.0-beta...v1.0.0
86
+ [0.3.0-beta]: https://github.com/calvinmcelvain/taskli/compare/v0.2.0-beta...v0.3.0-beta
87
+ [0.2.0-beta]: https://github.com/calvinmcelvain/taskli/compare/v0.1.0-beta...v0.2.0-beta
88
+ [0.1.0-beta]: https://github.com/calvinmcelvain/taskli/releases/tag/v0.1.0-beta
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Calvin W. McElvain
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.5
2
+ Name: taskli-cli
3
+ Version: 1.0.0
4
+ Summary: Simple CLI for tracking todo lists.
5
+ Project-URL: Homepage, https://github.com/calvinmcelvain/taskli
6
+ Project-URL: Repository, https://github.com/calvinmcelvain/taskli
7
+ Project-URL: Issues, https://github.com/calvinmcelvain/taskli/issues
8
+ Project-URL: Changelog, https://github.com/calvinmcelvain/taskli/blob/main/CHANGELOG.md
9
+ Project-URL: Documentation, https://github.com/calvinmcelvain/taskli/blob/main/docs/reference.md
10
+ Author-email: "Calvin W. McElvain" <mcelvain1@hotmail.com>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: cli,productivity,task-list,tasks,terminal,todo
14
+ Classifier: Development Status :: 5 - Production/Stable
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Utilities
23
+ Requires-Python: >=3.12
24
+ Requires-Dist: argcomplete<4,>=3.0
25
+ Requires-Dist: pydantic>=2.0
26
+ Requires-Dist: rich>=13.0
27
+ Description-Content-Type: text/markdown
28
+
29
+ <div align="center">
30
+
31
+ # taskli
32
+
33
+ **Nested task lists for your terminal.**
34
+ One command, one JSON file per list, and output that's actually nice to read.
35
+
36
+ [![PyPI](https://img.shields.io/pypi/v/taskli-cli)](https://pypi.org/project/taskli-cli/)
37
+ [![CI](https://github.com/calvinmcelvain/taskli/actions/workflows/ci.yml/badge.svg)](https://github.com/calvinmcelvain/taskli/actions/workflows/ci.yml)
38
+ ![Python](https://img.shields.io/pypi/pyversions/taskli-cli)
39
+ ![Type checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue)
40
+
41
+ [Install](#install) · [Quickstart](#quickstart) · [Tour](#tour) · [Cheat sheet](#cheat-sheet) · [Reference](https://github.com/calvinmcelvain/taskli/blob/main/docs/reference.md)
42
+
43
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/hero.svg" alt="tk work --all: a tree of tasks with subtasks, priorities, tags, and color-coded due dates" width="760">
44
+
45
+ </div>
46
+
47
+ ## Install
48
+
49
+ ```bash
50
+ uv tool install taskli-cli
51
+ ```
52
+
53
+ That puts `tk` (and its alias `taskli`) on your `PATH`. It needs Python 3.12+.
54
+ If `tk` isn't found afterwards, run `uv tool update-shell` once.
55
+
56
+ <details>
57
+ <summary>Using pipx, or installing from source</summary>
58
+
59
+ ```bash
60
+ pipx install taskli-cli
61
+ ```
62
+
63
+ To install the latest from GitHub instead:
64
+
65
+ ```bash
66
+ uv tool install git+https://github.com/calvinmcelvain/taskli.git
67
+ ```
68
+
69
+ To hack on it, see [CONTRIBUTING](https://github.com/calvinmcelvain/taskli/blob/main/CONTRIBUTING.md).
70
+
71
+ </details>
72
+
73
+ ## Quickstart
74
+
75
+ ```bash
76
+ tk -a "Buy oat milk" # goes to your inbox
77
+ tk work -a "Ship v2" -p high --due friday # any list, created on demand
78
+ tk work.meetings -a "Review roadmap" # a sublist of work
79
+ tk work --all # see work and everything under it
80
+ ```
81
+
82
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/quickstart.svg" alt="Adding items to the inbox, a work list, and a work.meetings sublist, then viewing the tree" width="640">
83
+
84
+ > [!TIP]
85
+ > `tk` on its own shows your inbox. Every action is a flag, so a list can be
86
+ > named anything and `tk work` never gets confused with a command.
87
+
88
+ ## The mental model
89
+
90
+ ```text
91
+ work a list
92
+ ├── 1 Ship v2 an item
93
+ │ └── 1.2 Tag the build a subtask (any depth: 1.2.1, ...)
94
+ └── work.meetings a sublist (up to 2 levels deep)
95
+ └── 1 Review roadmap
96
+ ```
97
+
98
+ Lists are named; items are numbered by position. That's the whole idea.
99
+
100
+ ## Tour
101
+
102
+ ### Check things off
103
+
104
+ Mark items done (`-d`), in progress (`-i`), or reset them (`-u`). Pass several
105
+ ids at once.
106
+
107
+ ```bash
108
+ tk work -i 2
109
+ tk work -d 3
110
+ ```
111
+
112
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/states.svg" alt="Marking one item in progress (cyan) and another done (dimmed and struck through)" width="560">
113
+
114
+ ### Plan your day
115
+
116
+ Set a due date with `--due`; overdue items turn red and today's turn yellow.
117
+ `tk --agenda` pulls everything due, from every list, into one timeline.
118
+
119
+ ```bash
120
+ tk work -a "Submit timesheet" --due friday
121
+ tk --agenda
122
+ ```
123
+
124
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/agenda.svg" alt="The agenda: items from several lists sorted by due date, overdue in red and due-today in yellow" width="640">
125
+
126
+ `--due` takes `today`, `tomorrow`, `3 days`, `2 weeks`, a weekday name, or
127
+ `MM-DD-YYYY`. More in [Working with tasks](https://github.com/calvinmcelvain/taskli/blob/main/docs/tasks.md#due-dates).
128
+
129
+ ### Find what matters
130
+
131
+ The default view is also a filter. Combine `--tag`, `-p`, `--today`,
132
+ `--undated`, and `--all`.
133
+
134
+ ```bash
135
+ tk work --all -p high # high priority, in work and every sublist
136
+ tk --today --all # everything due today, across every list
137
+ ```
138
+
139
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/filter.svg" alt="High-priority items in work and its meetings sublist" width="640">
140
+
141
+ ### Break work down
142
+
143
+ Nest subtasks with `--under`. Ids become dotted paths (`1.2`) that every
144
+ command understands.
145
+
146
+ ```bash
147
+ tk work -a "Cut release branch" --under 1
148
+ tk work -D 1 # full detail: description, timestamps, subtasks
149
+ ```
150
+
151
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/details.svg" alt="The detail view of one task, listing its description and subtasks" width="560">
152
+
153
+ ### Organize your lists
154
+
155
+ ```bash
156
+ tk groceries --new --color green # color-code a list
157
+ tk work -mv later 2 3 # move items between lists
158
+ tk work --rename job # renames sublists too
159
+ tk --lists
160
+ ```
161
+
162
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/lists.svg" alt="All lists shown as a color-coded tree" width="360">
163
+
164
+ ## Cheat sheet
165
+
166
+ | I want to... | Type this |
167
+ |---|---|
168
+ | add a task | `tk work -a "Ship v2" -p high --tag release` |
169
+ | see a list | `tk work` |
170
+ | see a list and its sublists | `tk work --all` |
171
+ | finish / start / reopen | `tk work -d 1` · `tk work -i 1` · `tk work -u 1` |
172
+ | change a task | `tk work -e 1 -t "Ship v2.1" --due tomorrow` |
173
+ | add a subtask | `tk work -a "Tag build" --under 1` |
174
+ | see everything due | `tk --agenda` |
175
+ | clear out finished work | `tk work --prune` |
176
+ | delete a task | `tk work -rm 1` |
177
+ | copy or move to another list | `tk work --copy later 1` · `tk work -mv later 1` |
178
+ | change a setting | `tk --config default_priority high` |
179
+
180
+ Every flag and rule lives in the [full reference](https://github.com/calvinmcelvain/taskli/blob/main/docs/reference.md).
181
+
182
+ ## Good to know
183
+
184
+ > [!WARNING]
185
+ > Ids are **positions**, not permanent. `-rm` and `--prune` renumber what's
186
+ > left, so don't reuse an id across commands that delete.
187
+
188
+ > [!WARNING]
189
+ > `-e --tag` **replaces** an item's tags. Use `--add-tag` to append.
190
+
191
+ > [!IMPORTANT]
192
+ > One action per call. If you mix flags from different groups (for example
193
+ > `--new` and `-a`), taskli runs one and warns about the others instead of
194
+ > guessing. `-d`, `-i`, `-u`, and `-rm` can combine freely.
195
+
196
+ ## More
197
+
198
+ - [Working with tasks](https://github.com/calvinmcelvain/taskli/blob/main/docs/tasks.md): priorities, tags, due dates, descriptions, subtasks
199
+ - [Lists and sublists](https://github.com/calvinmcelvain/taskli/blob/main/docs/lists.md): nesting, colors, moving, cascading delete and rename
200
+ - [Configuration](https://github.com/calvinmcelvain/taskli/blob/main/docs/config.md): every setting
201
+ - [Tab completion](https://github.com/calvinmcelvain/taskli/blob/main/docs/completion.md): bash, zsh, PowerShell
202
+ - [Stability](https://github.com/calvinmcelvain/taskli/blob/main/docs/stability.md): what stays compatible across 1.x
203
+ - [Changelog](https://github.com/calvinmcelvain/taskli/blob/main/CHANGELOG.md)
204
+ - [Contributing](https://github.com/calvinmcelvain/taskli/blob/main/CONTRIBUTING.md)
205
+
206
+ Your data lives in `~/.taskli` (override with `TASKLI_PATH`). Run `tk --path` to see it.
207
+
208
+ Released under the [MIT License](https://github.com/calvinmcelvain/taskli/blob/main/LICENSE).
@@ -0,0 +1,180 @@
1
+ <div align="center">
2
+
3
+ # taskli
4
+
5
+ **Nested task lists for your terminal.**
6
+ One command, one JSON file per list, and output that's actually nice to read.
7
+
8
+ [![PyPI](https://img.shields.io/pypi/v/taskli-cli)](https://pypi.org/project/taskli-cli/)
9
+ [![CI](https://github.com/calvinmcelvain/taskli/actions/workflows/ci.yml/badge.svg)](https://github.com/calvinmcelvain/taskli/actions/workflows/ci.yml)
10
+ ![Python](https://img.shields.io/pypi/pyversions/taskli-cli)
11
+ ![Type checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue)
12
+
13
+ [Install](#install) · [Quickstart](#quickstart) · [Tour](#tour) · [Cheat sheet](#cheat-sheet) · [Reference](https://github.com/calvinmcelvain/taskli/blob/main/docs/reference.md)
14
+
15
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/hero.svg" alt="tk work --all: a tree of tasks with subtasks, priorities, tags, and color-coded due dates" width="760">
16
+
17
+ </div>
18
+
19
+ ## Install
20
+
21
+ ```bash
22
+ uv tool install taskli-cli
23
+ ```
24
+
25
+ That puts `tk` (and its alias `taskli`) on your `PATH`. It needs Python 3.12+.
26
+ If `tk` isn't found afterwards, run `uv tool update-shell` once.
27
+
28
+ <details>
29
+ <summary>Using pipx, or installing from source</summary>
30
+
31
+ ```bash
32
+ pipx install taskli-cli
33
+ ```
34
+
35
+ To install the latest from GitHub instead:
36
+
37
+ ```bash
38
+ uv tool install git+https://github.com/calvinmcelvain/taskli.git
39
+ ```
40
+
41
+ To hack on it, see [CONTRIBUTING](https://github.com/calvinmcelvain/taskli/blob/main/CONTRIBUTING.md).
42
+
43
+ </details>
44
+
45
+ ## Quickstart
46
+
47
+ ```bash
48
+ tk -a "Buy oat milk" # goes to your inbox
49
+ tk work -a "Ship v2" -p high --due friday # any list, created on demand
50
+ tk work.meetings -a "Review roadmap" # a sublist of work
51
+ tk work --all # see work and everything under it
52
+ ```
53
+
54
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/quickstart.svg" alt="Adding items to the inbox, a work list, and a work.meetings sublist, then viewing the tree" width="640">
55
+
56
+ > [!TIP]
57
+ > `tk` on its own shows your inbox. Every action is a flag, so a list can be
58
+ > named anything and `tk work` never gets confused with a command.
59
+
60
+ ## The mental model
61
+
62
+ ```text
63
+ work a list
64
+ ├── 1 Ship v2 an item
65
+ │ └── 1.2 Tag the build a subtask (any depth: 1.2.1, ...)
66
+ └── work.meetings a sublist (up to 2 levels deep)
67
+ └── 1 Review roadmap
68
+ ```
69
+
70
+ Lists are named; items are numbered by position. That's the whole idea.
71
+
72
+ ## Tour
73
+
74
+ ### Check things off
75
+
76
+ Mark items done (`-d`), in progress (`-i`), or reset them (`-u`). Pass several
77
+ ids at once.
78
+
79
+ ```bash
80
+ tk work -i 2
81
+ tk work -d 3
82
+ ```
83
+
84
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/states.svg" alt="Marking one item in progress (cyan) and another done (dimmed and struck through)" width="560">
85
+
86
+ ### Plan your day
87
+
88
+ Set a due date with `--due`; overdue items turn red and today's turn yellow.
89
+ `tk --agenda` pulls everything due, from every list, into one timeline.
90
+
91
+ ```bash
92
+ tk work -a "Submit timesheet" --due friday
93
+ tk --agenda
94
+ ```
95
+
96
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/agenda.svg" alt="The agenda: items from several lists sorted by due date, overdue in red and due-today in yellow" width="640">
97
+
98
+ `--due` takes `today`, `tomorrow`, `3 days`, `2 weeks`, a weekday name, or
99
+ `MM-DD-YYYY`. More in [Working with tasks](https://github.com/calvinmcelvain/taskli/blob/main/docs/tasks.md#due-dates).
100
+
101
+ ### Find what matters
102
+
103
+ The default view is also a filter. Combine `--tag`, `-p`, `--today`,
104
+ `--undated`, and `--all`.
105
+
106
+ ```bash
107
+ tk work --all -p high # high priority, in work and every sublist
108
+ tk --today --all # everything due today, across every list
109
+ ```
110
+
111
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/filter.svg" alt="High-priority items in work and its meetings sublist" width="640">
112
+
113
+ ### Break work down
114
+
115
+ Nest subtasks with `--under`. Ids become dotted paths (`1.2`) that every
116
+ command understands.
117
+
118
+ ```bash
119
+ tk work -a "Cut release branch" --under 1
120
+ tk work -D 1 # full detail: description, timestamps, subtasks
121
+ ```
122
+
123
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/details.svg" alt="The detail view of one task, listing its description and subtasks" width="560">
124
+
125
+ ### Organize your lists
126
+
127
+ ```bash
128
+ tk groceries --new --color green # color-code a list
129
+ tk work -mv later 2 3 # move items between lists
130
+ tk work --rename job # renames sublists too
131
+ tk --lists
132
+ ```
133
+
134
+ <img src="https://raw.githubusercontent.com/calvinmcelvain/taskli/main/docs/assets/lists.svg" alt="All lists shown as a color-coded tree" width="360">
135
+
136
+ ## Cheat sheet
137
+
138
+ | I want to... | Type this |
139
+ |---|---|
140
+ | add a task | `tk work -a "Ship v2" -p high --tag release` |
141
+ | see a list | `tk work` |
142
+ | see a list and its sublists | `tk work --all` |
143
+ | finish / start / reopen | `tk work -d 1` · `tk work -i 1` · `tk work -u 1` |
144
+ | change a task | `tk work -e 1 -t "Ship v2.1" --due tomorrow` |
145
+ | add a subtask | `tk work -a "Tag build" --under 1` |
146
+ | see everything due | `tk --agenda` |
147
+ | clear out finished work | `tk work --prune` |
148
+ | delete a task | `tk work -rm 1` |
149
+ | copy or move to another list | `tk work --copy later 1` · `tk work -mv later 1` |
150
+ | change a setting | `tk --config default_priority high` |
151
+
152
+ Every flag and rule lives in the [full reference](https://github.com/calvinmcelvain/taskli/blob/main/docs/reference.md).
153
+
154
+ ## Good to know
155
+
156
+ > [!WARNING]
157
+ > Ids are **positions**, not permanent. `-rm` and `--prune` renumber what's
158
+ > left, so don't reuse an id across commands that delete.
159
+
160
+ > [!WARNING]
161
+ > `-e --tag` **replaces** an item's tags. Use `--add-tag` to append.
162
+
163
+ > [!IMPORTANT]
164
+ > One action per call. If you mix flags from different groups (for example
165
+ > `--new` and `-a`), taskli runs one and warns about the others instead of
166
+ > guessing. `-d`, `-i`, `-u`, and `-rm` can combine freely.
167
+
168
+ ## More
169
+
170
+ - [Working with tasks](https://github.com/calvinmcelvain/taskli/blob/main/docs/tasks.md): priorities, tags, due dates, descriptions, subtasks
171
+ - [Lists and sublists](https://github.com/calvinmcelvain/taskli/blob/main/docs/lists.md): nesting, colors, moving, cascading delete and rename
172
+ - [Configuration](https://github.com/calvinmcelvain/taskli/blob/main/docs/config.md): every setting
173
+ - [Tab completion](https://github.com/calvinmcelvain/taskli/blob/main/docs/completion.md): bash, zsh, PowerShell
174
+ - [Stability](https://github.com/calvinmcelvain/taskli/blob/main/docs/stability.md): what stays compatible across 1.x
175
+ - [Changelog](https://github.com/calvinmcelvain/taskli/blob/main/CHANGELOG.md)
176
+ - [Contributing](https://github.com/calvinmcelvain/taskli/blob/main/CONTRIBUTING.md)
177
+
178
+ Your data lives in `~/.taskli` (override with `TASKLI_PATH`). Run `tk --path` to see it.
179
+
180
+ Released under the [MIT License](https://github.com/calvinmcelvain/taskli/blob/main/LICENSE).
@@ -0,0 +1,34 @@
1
+ # Shell completion scripts
2
+
3
+ Pre-generated [`argcomplete`](https://github.com/kislyuk/argcomplete) shims for
4
+ `tk` / `taskli` tab-completion. Both entry points are wired by both files.
5
+
6
+ | File | Shells |
7
+ |---|---|
8
+ | `taskli.sh` | bash, zsh |
9
+ | `taskli.ps1` | PowerShell |
10
+
11
+ They are checked in so a new terminal pays no generation cost and nothing needs
12
+ to be on `PATH`. End users `source` (bash/zsh) or dot-source (PowerShell) one
13
+ file — see the `## Shell completion` section of the top-level `README.md`.
14
+
15
+ Packaging (`pyproject.toml`) ships this directory in the sdist and maps it into
16
+ the wheel at `<prefix>/share/taskli/completions/` (for a `uv tool install`, that
17
+ is `$(uv tool dir)/taskli-cli/share/taskli/completions/`).
18
+
19
+ ## Regenerating
20
+
21
+ These are the **verbatim** output of `register-python-argcomplete` — do not
22
+ hand-edit them. The shims are parser-independent (they exec `tk` with
23
+ `_ARGCOMPLETE=1` at TAB time), so regeneration is only needed when `argcomplete`
24
+ itself is upgraded.
25
+
26
+ ```bash
27
+ register-python-argcomplete -s bash tk taskli > completions/taskli.sh
28
+ register-python-argcomplete -s powershell tk taskli > completions/taskli.ps1
29
+ ```
30
+
31
+ Generated with **argcomplete 3.7.2**. When you regenerate, update that version
32
+ here and `EXPECTED_ARGCOMPLETE` in `tests/test_completions.py` — the guard test
33
+ compares the committed files against a fresh generation only when the installed
34
+ `argcomplete` matches that version.
@@ -0,0 +1,38 @@
1
+
2
+ Register-ArgumentCompleter -Native -CommandName tk -ScriptBlock {
3
+ param($commandName, $wordToComplete, $cursorPosition)
4
+ $completion_file = New-TemporaryFile
5
+ $env:ARGCOMPLETE_USE_TEMPFILES = 1
6
+ $env:_ARGCOMPLETE_STDOUT_FILENAME = $completion_file
7
+ $env:COMP_LINE = $wordToComplete
8
+ $env:COMP_POINT = $cursorPosition
9
+ $env:_ARGCOMPLETE = 1
10
+ $env:_ARGCOMPLETE_SUPPRESS_SPACE = 0
11
+ $env:_ARGCOMPLETE_IFS = "`n"
12
+ $env:_ARGCOMPLETE_SHELL = "powershell"
13
+ tk 2>&1 | Out-Null
14
+
15
+ Get-Content $completion_file | ForEach-Object {
16
+ [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
17
+ }
18
+ Remove-Item $completion_file, Env:\_ARGCOMPLETE_STDOUT_FILENAME, Env:\ARGCOMPLETE_USE_TEMPFILES, Env:\COMP_LINE, Env:\COMP_POINT, Env:\_ARGCOMPLETE, Env:\_ARGCOMPLETE_SUPPRESS_SPACE, Env:\_ARGCOMPLETE_IFS, Env:\_ARGCOMPLETE_SHELL
19
+ }
20
+
21
+ Register-ArgumentCompleter -Native -CommandName taskli -ScriptBlock {
22
+ param($commandName, $wordToComplete, $cursorPosition)
23
+ $completion_file = New-TemporaryFile
24
+ $env:ARGCOMPLETE_USE_TEMPFILES = 1
25
+ $env:_ARGCOMPLETE_STDOUT_FILENAME = $completion_file
26
+ $env:COMP_LINE = $wordToComplete
27
+ $env:COMP_POINT = $cursorPosition
28
+ $env:_ARGCOMPLETE = 1
29
+ $env:_ARGCOMPLETE_SUPPRESS_SPACE = 0
30
+ $env:_ARGCOMPLETE_IFS = "`n"
31
+ $env:_ARGCOMPLETE_SHELL = "powershell"
32
+ taskli 2>&1 | Out-Null
33
+
34
+ Get-Content $completion_file | ForEach-Object {
35
+ [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
36
+ }
37
+ Remove-Item $completion_file, Env:\_ARGCOMPLETE_STDOUT_FILENAME, Env:\ARGCOMPLETE_USE_TEMPFILES, Env:\COMP_LINE, Env:\COMP_POINT, Env:\_ARGCOMPLETE, Env:\_ARGCOMPLETE_SUPPRESS_SPACE, Env:\_ARGCOMPLETE_IFS, Env:\_ARGCOMPLETE_SHELL
38
+ }