simple-project-tracker 1.0.0__py3-none-any.whl

simple_project_tracker-1.0.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: simple-project-tracker
+Version: 1.0.0
+Summary: Simple project tracker
+Author-email: MattFor <mattfor@relaxy.xyz>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MattFor/tracker
+Project-URL: Source, https://github.com/MattFor/tracker
+Project-URL: Mirror, https://codeberg.org/MattFor/tracker
+Project-URL: Issues, https://github.com/MattFor/tracker/issues
+Project-URL: Changelog, https://github.com/MattFor/tracker/blob/master/CHANGELOG.md
+Keywords: cli,projects,git,tracker
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# simple-project-tracker
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A simple, but very customizable tracker to keep track of your projects, their states and
+your notes on them.
+
+```
+TID | ID | NAME                          | STATUS  | LAST TOUCHED | NOTE
+--- | -- | ----------------------------- | ------- | ------------ | ---------------------
+1   | 8  | tracker                       | dev     | 1m ago       | release 1.0.0 today
+2   | 3  | von-neumann-machine-simulator | dev     | 23m ago      | review saturday
+3   | 26 | discord-profile-studio        | stable  | 1h ago
+```
+
+## Contents
+
+- [Install](#install)
+- [Commands](#commands)
+- [Selecting projects](#selecting-projects)
+- [Configuration](#configuration)
+- [Development](#development)
+- [License](#license)
+
+## Install
+
+```sh
+./install.sh             # ~/.local
+sudo ./install.sh        # /usr/local
+./install.sh --daemon    # also install the daemon autostart entry
+./install.sh --uninstall
+```
+
+Python 3.11+. Then `t init ~/(your project directory)` to fill the database.
+
+## Commands
+
+| Command      | Aliases           | What it does                                                         |
+|--------------|-------------------|----------------------------------------------------------------------|
+| `list`       | `l`, `ls`         | List projects, with search, regex, filters and setting overrides     |
+| `check`      | `c`, `cc`, `info` | Everything about a project: git state, size, language, version, note |
+| `add`        | `a`               | Track a project, or scan a directory and track what is inside        |
+| `remove`     | `rm`, `r`, `del`  | Stop tracking projects (files untouched)                             |
+| `forget`     | `ignore`          | Stop tracking and keep scans from finding it again                   |
+| `edit`       | `e`               | Change a `status` or a `note`                                        |
+| `note`       | `n`, `sn`         | Set a note without naming the field                                  |
+| `status`     | `st`, `ss`        | List statuses, set one, or move every project from one to another    |
+| `init`       | `i`, `scan`       | Scan a directory and merge the result into the database              |
+| `path`       | `p`, `where`      | Print a project's path, e.g. `cd "$(t path tracker)"`                |
+| `undo`       | `u`, `revert`     | Take back the last change, undo again to put it back                 |
+| `stats`      | `summary`         | Totals, a breakdown by status, most and least recently touched       |
+| `settings`   | `s`, `config`     | Show, edit, get or set the configuration                             |
+| `completion` |                   | Print a shell completion script for bash, zsh or fish                |
+| `daemon`     | `d`, `bg`         | `start`, `stop`, `restart`, `status`, `log`, `run`                   |
+
+The project goes before or after the command, whichever reads better, and a command fuses
+with its own action:
+
+```sh
+t 12 es blocked        # edit status  also: t edit 12 status blocked
+t 12 sn review sunday  # set note     also: t note 12 review sunday
+t dst                  # daemon status
+t sset ll 30           # settings set display.list_limit 30
+```
+
+A bare word defaults to a project lookup.
+
+```sh
+t tra          # the check view for tracker
+t stable       # nothing is called that, so every stable project
+t all          # everything, no limit
+```
+
+For more information do: `t help`, `t help <command>` or `t help <topic>`. The full guide
+is within `man tracker`.
+
+## Selecting projects
+
+| Selector    | Means                                                     |
+|-------------|-----------------------------------------------------------|
+| `12`        | ID or TID 12                                              |
+| `i:12`      | The permanent ID, `id:` and `#12` too                     |
+| `t:12`      | The temporary ID, `tid:`, `@12` and `:12` too             |
+| `3-7`,`5+3` | A range, either direction, or a project and the next few  |
+| `s:blocked` | Every project with that status, `st:` and `status:` too   |
+| `name`      | Exact or partial name, or a path, tab completion included |
+| `all`       | Every tracked project                                     |
+
+A temporary ID is the index of the latest output.
+
+When a partial name matches several projects, it's settled by
+`projects.conflict_resolution_preference`.
+
+## Configuration
+
+```sh
+t settings                    # everything (default deviations marked)
+t settings edit               # open in $EDITOR
+t sset list_limit 30          # rewrites that one line
+t list ll=5 rt=true           # override for one command only
+```
+
+A setting can be named in full, by its bare name, by a prefix, by the start of every word
+or by its initials, with the section shortening the same way: `display.list_limit`,
+`list_limit`, `list_lim`, `l_l`, `ll`, `d.ll`. Ambiguities are reported.
+
+| Setting                             | What it does                                                |
+|-------------------------------------|-------------------------------------------------------------|
+| `display.filter`                    | Filters every listing, e.g. `["-s:archive"]`                |
+| `display.columns`, `display.format` | Which columns, or a row layout of your own                  |
+| `display.relative_times`            | `2 days ago` instead of a timestamp                         |
+| `display.name_max_width`            | Shorten long names, `truncate` or `abbreviate`              |
+| `sorting.by`, `sorting.direction`   | `last_touched`, `last_used`, `name`, `status`, `id`, `path` |
+| `projects.ignore`, `.ignore_files`  | Directories and files that never count as your own work     |
+| `projects.auto_status`              | Status from how long ago a project was touched              |
+| `scan.detect_moves`                 | A moved project keeps its entry instead of looking deleted  |
+| `daemon.paths`, `daemon.interval`   | What the background scanner watches, and how often          |
+
+Notes can colour themselves: `t note 12 {red}broken{/} since friday`.
+
+## Development
+
+```sh
+make dev      # editable install plus ruff, basedpyright, pytest
+make check    # format, lint, types and tests (what CI runs)
+```
+
+## Disclosure
+
+LLMs were used to:
+
+- write the help section
+- write the man page
+- check for critical issues and annotation errors
+
+HOWEVER, the output was then manually reviewed and issues were fixed by a human.
+
+## License
+
+MIT [LICENSE](LICENSE).  
+By MattFor.

simple_project_tracker-1.0.0.dist-info/RECORD

@@ -0,0 +1,47 @@
+simple_project_tracker-1.0.0.dist-info/licenses/LICENSE,sha256=g3pm9QNICLWqd781GBeloDbp5XMlwRrBCWOn1dlcW4I,1064
+tracker/__init__.py,sha256=eBsP_LY8s8vvzKVwBVhV1pp90hmKGRcTRijyFL72L6k,102
+tracker/__main__.py,sha256=jeGiXw1aaE09qtu4RQW_xa1kzMpGrj2XcRe2LzaV16w,91
+tracker/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tracker/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tracker/cli/app.py,sha256=qm2DXg5K4xo4GzjYNLxVB6PcCU61lYSb6iJLxdaMMTE,8012
+tracker/cli/commands.py,sha256=IYNaqmR6Luf5eJaB9bBr7aALAndtImxSwSl3b8sB8nY,28338
+tracker/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tracker/config/defaults.py,sha256=unPiz7O_ex0p1zhgR_HvbvJljKdIEd6fI8-4cLSUywE,3442
+tracker/config/keys.py,sha256=K-2c5w_ep32p4QahAM4BO1DCBGgLjAuCDsGVtw1YM-g,2082
+tracker/config/metadata.py,sha256=wJ9jHqzqTWmT3EO65MNPLeSZGj4L2x8wHchU5ZbkN_k,1786
+tracker/config/paths.py,sha256=vmcLRYToVOJ64eV6K_yILXpXpu_2fpSEK6UYhGXfEz0,3324
+tracker/config/settings.py,sha256=_oS9yOt64Kutk8yzZX6ohcaA_lcgTwKkr78k8j2oyxs,5314
+tracker/config/writer.py,sha256=cJHPnldKOSnl7qOKk97SKcHjN1nv52LWfuc_PK5xXAQ,2478
+tracker/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tracker/core/daemon.py,sha256=2mGaVd0yNPo4N77nG81_6uFhIecR7UaqP6Kk-nQrWvQ,13743
+tracker/core/discovery.py,sha256=sbKgfyC3HKbNwKHL9D99cH7oqvZpJp-Xzf51lztyOwg,4788
+tracker/core/frecency.py,sha256=zc5n3u-VsYO1H-UAyzvZMPbS_UTfkRstEq5M-Z0D8Wc,2528
+tracker/core/identity.py,sha256=Iyb1FthX9cfKxZp-7SOH5dWh6NLX54hepgHTE9HRd0E,2461
+tracker/core/inspect.py,sha256=zVLD0l-YirUYTipw9Th3Sw5z0sk1rplWRp8S2nwwHeU,7846
+tracker/core/labels.py,sha256=HKejtaEgEcQhx-lOeOskJ7bpE1hgvL9HOhl2feGngrQ,2324
+tracker/core/models.py,sha256=-lp9-mkHEXHzDkV6AlqFN8BlQlCmtUXFtMlDuHSRrjA,3152
+tracker/core/selection.py,sha256=XOyk_Zd5SGkEN_zuD1ZiSjov5g5SHT_S6bOll191um0,15005
+tracker/core/storage.py,sha256=PNdPxDGoQvvT3D5pdcuenFwC7Eit31wYMc7E_re76wk,1322
+tracker/core/undo.py,sha256=ps2daqIzFehcVcWLS3V86ypf7M3fYhWZUgExcBM59t8,1536
+tracker/core/view.py,sha256=54r3PraDOvbvPLj32TI8_Ysrybu-gB2uvLdZMoNtgRg,1125
+tracker/share/completion.bash,sha256=VDQf36XfdnXfFYlhBBYghZhfWBPRSBT2dRT8iznF8so,208
+tracker/share/completion.fish,sha256=0vVvOmX1CtYONmW-FDkoUirZkX4R8A3FIyawTw3ExS0,300
+tracker/share/completion.zsh,sha256=Kwp4N06wp2ZRZ_jiUhXz5r0ZF3xN5f4NzI-s0YRaSls,234
+tracker/share/help.txt,sha256=eiW14kjKYZVObbYM3NudaZVQfkGKQwid1KkX9TekUD4,26030
+tracker/share/settings.toml,sha256=i-2qsdduECyhqy8zTyG0O4tKu4h5CqGmdx6TDLNTu88,6513
+tracker/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tracker/ui/ansi.py,sha256=axUok7BgAFNPLkRrxI6DEOXUtUH3pPro0tmaIcjI9_I,2353
+tracker/ui/ask.py,sha256=OxBM7iDYFpN3GX1ugCdoTqIQeEVPS25z-7u9qrtfUVY,434
+tracker/ui/details.py,sha256=muuG2QuryfH-i8JKYCl6MnMQrGxTRXbo868zDi8yD60,4398
+tracker/ui/help.py,sha256=RUfBYR0wUo73EsF2qJ1dx94qG6eIZpMGzUDVrLfloRA,4652
+tracker/ui/render.py,sha256=RWUAMxV-6si6dP0lFU_DIpApAeQK0iaToZ2rtDSCzjY,12198
+tracker/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tracker/util/compat.py,sha256=5IO-phVQPQcw6jbFEWVpHNFpxfcRFVeJGotJxz3CaC4,378
+tracker/util/files.py,sha256=opy2CpwzgNy1g4odLthMMvzqCJJSXAqsXDtKU8jHaQU,2110
+tracker/util/text.py,sha256=3pURviQFZ83dpfidVs5kQ60c4dggp7ts8elwl-j4ejA,5606
+tracker/util/unknown.py,sha256=gIDNUrZ0qLgFVy4bO7yvl5j8H6uJPayMUp1DE6c7RJ0,891
+simple_project_tracker-1.0.0.dist-info/METADATA,sha256=QNq2XhAs2YWaoX7uxrYh0xBJF09zS0Jr6qT5112NS_o,7991
+simple_project_tracker-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+simple_project_tracker-1.0.0.dist-info/entry_points.txt,sha256=tOQFoJ-Ep9Rav8ZdFimrr1mhlCzj9KkK2xmndZ9FuXs,74
+simple_project_tracker-1.0.0.dist-info/top_level.txt,sha256=5d6-AgJ9PHuONh0ZOHelH0Z2fl97aKnDzEaSXzORM4w,8
+simple_project_tracker-1.0.0.dist-info/RECORD,,

simple_project_tracker-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simple_project_tracker-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+t = tracker.cli.app:main
+tracker = tracker.cli.app:main

simple_project_tracker-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MattFor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simple_project_tracker-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tracker

tracker/__init__.py

@@ -0,0 +1,5 @@
+from tracker.config.metadata import project
+
+__all__ = ["__version__"]
+
+__version__ = project.version

tracker/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from tracker.cli.app import main
+
+if __name__ == "__main__":
+	sys.exit(main())

tracker/cli/app.py

@@ -0,0 +1,393 @@
+import sys
+
+from typing import Any
+
+from tracker.ui import ansi
+from tracker.cli import commands
+from tracker.ui.ansi import C
+from tracker.core.storage import load_data
+from tracker.config.settings import Settings
+from tracker.ui.render import print_projects
+from tracker.cli.commands import Context, Handler
+
+COMMANDS: dict[str, str] = {
+	"version": "version",
+	"v": "version",
+	"help": "help",
+	"h": "help",
+	"list": "list",
+	"l": "list",
+	"ls": "list",
+	"add": "add",
+	"a": "add",
+	"remove": "remove",
+	"rm": "remove",
+	"r": "remove",
+	"delete": "remove",
+	"del": "remove",
+	"forget": "forget",
+	"f": "forget",
+	"ignore": "forget",
+	"completion": "completion",
+	"completions": "completion",
+	"check": "check",
+	"c": "check",
+	"cc": "check",
+	"info": "check",
+	"edit": "edit",
+	"e": "edit",
+	"note": "note",
+	"n": "note",
+	"sn": "note",
+	"status": "status",
+	"st": "status",
+	"ss": "status",
+	"init": "init",
+	"i": "init",
+	"scan": "init",
+	"settings": "settings",
+	"s": "settings",
+	"config": "settings",
+	"conf": "settings",
+	"daemon": "daemon",
+	"d": "daemon",
+	"daemonize": "daemon",
+	"daemonise": "daemon",
+	"background": "daemon",
+	"b": "daemon",
+	"bg": "daemon",
+	"path": "path",
+	"p": "path",
+	"where": "path",
+	"stats": "stats",
+	"stat": "stats",
+	"summary": "stats",
+	"undo": "undo",
+	"u": "undo",
+	"revert": "undo",
+}
+
+HANDLERS: dict[str, Handler] = {
+	"version": commands.command_version,
+	"help": commands.command_help,
+	"list": commands.command_list,
+	"add": commands.command_add,
+	"remove": commands.command_remove,
+	"check": commands.command_check,
+	"edit": commands.command_edit,
+	"init": commands.command_init,
+	"settings": commands.command_settings,
+	"daemon": commands.command_daemon,
+	"path": commands.command_path,
+	"stats": commands.command_stats,
+	"undo": commands.command_undo,
+	"show": commands.command_show,
+	"note": commands.command_note,
+	"status": commands.command_status,
+	"forget": commands.command_forget,
+	"completion": commands.command_completion,
+}
+
+GREEDY = frozenset({"add", "completion", "edit", "note", "status"})
+
+SUBJECT = frozenset(
+	{"check", "edit", "forget", "note", "path", "remove", "show", "status"}
+)
+
+ACTIONS: dict[str, frozenset[str]] = {
+	"edit": frozenset(commands.FIELD_ALIASES),
+	"forget": frozenset({"list", "l", "show", "clear", "c", "reset", "allow"}),
+	"settings": frozenset(
+		{"edit", "e", "path", "p", "where", "w", "get", "g", "set", "s"}
+	),
+	"daemon": frozenset(
+		{
+			"start",
+			"s",
+			"stop",
+			"kill",
+			"k",
+			"restart",
+			"r",
+			"status",
+			"st",
+			"state",
+			"log",
+			"logs",
+			"l",
+			"run",
+			"foreground",
+			"fg",
+		}
+	),
+}
+
+# Words a command keeps for itself instead of reading them as another command
+KEYWORDS: dict[str, frozenset[str]] = {"list": commands.LIMIT_KEYWORDS}
+
+LITERAL = "--"
+
+VERBOSE_FLAGS = frozenset({"verbose", "vv"})
+
+YES_FLAGS = frozenset({"yes", "y", "force", "f"})
+
+COLOUR_FLAGS = frozenset({"color", "colour"})
+NO_COLOUR_FLAGS = frozenset({"no-color", "no-colour", "nocolor", "nocolour"})
+
+
+def normalise(token: str) -> str:
+	return token.lower().strip("-")
+
+
+def command_of(token: str) -> str | None:
+	return COMMANDS.get(normalise(token))
+
+
+def greedy(token: str) -> bool:
+	name = command_of(token)
+
+	if name is None:
+		pair = fuse(token)
+		name = pair[0] if pair else None
+
+	return name in GREEDY
+
+
+def fuse(token: str) -> tuple[str, str] | None:
+	key = normalise(token)
+
+	for cut in range(1, len(key)):
+		name = COMMANDS.get(key[:cut])
+
+		if name is None:
+			continue
+
+		action = key[cut:]
+
+		if action in ACTIONS.get(name, frozenset()):
+			return name, action
+
+	return None
+
+
+def expand(args: list[str]) -> list[str]:
+	expanded: list[str] = []
+	literal = False
+
+	for token in args:
+		if literal:
+			expanded.append(token)
+			continue
+
+		if token == LITERAL:
+			literal = True
+			expanded.append(token)
+			continue
+
+		name = command_of(token)
+
+		if name is not None:
+			expanded.append(token)
+			literal = name in GREEDY
+			continue
+
+		pair = fuse(token)
+
+		if pair is None:
+			expanded.append(token)
+			continue
+
+		literal = pair[0] in GREEDY
+
+		expanded.extend(pair)
+
+	return expanded
+
+
+def help_request(args: list[str]) -> list[str] | None:
+	for index, token in enumerate(args):
+		if token == LITERAL:
+			return None
+
+		name = command_of(token)
+
+		if name == "help":
+			if index:
+				for previous in reversed(args[:index]):
+					owner = command_of(previous)
+
+					if owner is not None:
+						return [owner, *args[index + 1 :]]
+
+			return args[index + 1 :]
+
+		if name in GREEDY:
+			following = index + 1
+
+			if following == len(args) - 1 and command_of(args[following]) == "help":
+				return [name]
+
+			return None
+
+	return None
+
+
+def split(args: list[str]) -> list[tuple[str, list[str]]]:
+	args = expand(args)
+
+	wanted = help_request(args)
+
+	if wanted is not None:
+		return [("help", wanted)]
+
+	literal = len(args)
+
+	if LITERAL in args:
+		literal = args.index(LITERAL)
+		del args[literal]
+
+	# noinspection shadowing-names
+	def command_at(index: int, owner: str = "") -> str | None:
+		if index >= literal:
+			return None
+
+		if normalise(args[index]) in KEYWORDS.get(owner, frozenset()):
+			return None
+
+		return command_of(args[index])
+
+	segments: list[tuple[str, list[str]]] = []
+
+	index = 0
+
+	while index < len(args):
+		name = command_at(index)
+		subject: list[str] = []
+
+		if name is None:
+			while index < len(args) and command_at(index) is None:
+				subject.append(args[index])
+				index += 1
+
+			name = command_at(index) if index < len(args) else None
+
+			if name is None or name not in SUBJECT:
+				segments.append(("show", subject))
+				continue
+
+		index += 1
+
+		if name in GREEDY:
+			segments.append((name, subject + args[index:]))
+			break
+
+		collected = list(subject)
+
+		if index < literal and normalise(args[index]) in ACTIONS.get(name, frozenset()):
+			collected.append(args[index])
+			index += 1
+
+		while index < len(args) and command_at(index, name) is None:
+			collected.append(args[index])
+			index += 1
+
+		segments.append((name, collected))
+
+	return segments
+
+
+def extract_flags(args: list[str]) -> tuple[list[str], dict[str, Any]]:
+	flags: dict[str, Any] = {"verbose": False, "yes": False, "colour": None}
+
+	remaining: list[str] = []
+	greedy_reached = False
+	literal = False
+
+	for token in args:
+		if literal:
+			remaining.append(token)
+			continue
+
+		if token == LITERAL:
+			literal = True
+			remaining.append(token)
+			continue
+
+		if greedy_reached and not token.startswith("-"):
+			remaining.append(token)
+			continue
+
+		if greedy(token):
+			greedy_reached = True
+
+		key = normalise(token)
+
+		if key in VERBOSE_FLAGS:
+			flags["verbose"] = True
+			continue
+
+		if token.startswith("-") and key in YES_FLAGS:
+			flags["yes"] = True
+			continue
+
+		if token.startswith("-") and key in NO_COLOUR_FLAGS:
+			flags["colour"] = False
+			continue
+
+		if token.startswith("-") and key in COLOUR_FLAGS:
+			flags["colour"] = True
+			continue
+
+		remaining.append(token)
+
+	return remaining, flags
+
+
+def main(argv: list[str] | None = None) -> int:
+	args = list(sys.argv[1:] if argv is None else argv)
+
+	args, flags = extract_flags(args)
+
+	settings = Settings()
+
+	colour = settings["output"]["colour"] if flags["colour"] is None else flags["colour"]
+	ansi.configure(bool(colour))
+
+	for problem in settings.problems:
+		print(f"{C.YELLOW}[WARNING] {problem}{C.RESET}", file=sys.stderr)
+
+	verbose = bool(flags["verbose"] or settings["logging"]["always_verbose"])
+
+	context = Context(
+		settings=settings,
+		data=load_data(settings),
+		verbose=verbose,
+		assume_yes=bool(flags["yes"]),
+	)
+
+	context.log(f"settings: {settings.path}")
+	context.log(f"projects: {len(context.data)}")
+
+	if not args:
+		print_projects(context.data, settings)
+		return 0
+
+	status = 0
+
+	for name, arguments in split(args):
+		handler = HANDLERS.get(name)
+
+		if handler is None:
+			print(f"[ERROR] unknown command '{name}'")
+			status = 1
+			continue
+
+		try:
+			status = handler(context, arguments) or status
+		except KeyboardInterrupt:
+			print()
+			return 130
+		except BrokenPipeError:
+			return 0
+
+	return status