fillipe-gsm · fillipe-gsm · Dec 11, 2025 · Dec 9, 2025 · Dec 9, 2025 · Dec 10, 2025
diff --git a/README.adoc b/README.adoc
@@ -5,9 +5,6 @@
 :toc-title: Kanban cli management
 :toc:
 
-
-Status: alpha
-
 This is a command-line tool to manage simple kanban boards.
 
 TODO: add a gif with the feature working.
@@ -32,13 +29,223 @@ Alternatively, if you have a specific Python environment that is active, a simpl
 pip install kanban-cli
 ----
 
-== Commands
+== Quickstart
+
+Start typing:
+
+[,sh]
+----
+kanban-cli tasks view-all
+----
+
+This will do two things: (i) create a `kanban.db` file to store your tasks (which can be changed as shown later), and (ii) query and print all existing tasks. If you started this in an empty file, you should see a message with no tasks available.
+
+Then, add a new task with
+
+[,sh]
+----
+kanban-cli tasks add
+----
+
+You should see a number of prompts to detail the task you want:
+
+* Title, which defaults to at most 50 characters;
+* Status, which defaults to one of "To-do", "In progress", "Review", "Done";
+* Priority, which defaults to "Lowest", "Low", "Normal", "High", "Highest";
+* Category, which defaults to at most 50 characters. Notice it autocompletes existing categories, if any;
+* Optional details, which are basically a free text with multiple lines, allowing text in the markdown style.
+
+After you fill these, you should see a tabular view of the task as exemplified below. Try adding more tasks.
+
+[,sh]
+----
+                                                                 Tasks
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃              To-do              ┃           In progress           ┃             Review             ┃              Done              ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ #1 [Normal] [personal]          │                                 │                                │                                │
+│ buy milk                        │                                 │                                │                                │
+└─────────────────────────────────┴─────────────────────────────────┴────────────────────────────────┴────────────────────────────────┘
+----
+
+The most common movements of a task is to change its status, which we refer to `promote` when moved up and `regress` when moved down. To promote the previous task, use its identification (`#1` shown in the example above) and type the following command:
+
+
+[,sh]
+----
+kanban-cli promote 1
+----
+
+which should change the column it currently belongs to. Try promoting it further or regressing it later.
+
+[,sh]
+----
+                                                                 Tasks
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃              To-do              ┃           In progress           ┃             Review             ┃              Done              ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│                                 │ #1 [Normal] [personal]          │                                │                                │
+│                                 │ buy milk                        │                                │                                │
+└─────────────────────────────────┴─────────────────────────────────┴────────────────────────────────┴────────────────────────────────┘
+----
+
+You can also get a more detailed view of a task with
+
+[,sh]
+----
+kanban-cli view 1
+----
+
+which displays all information about a task, including its details (if any).
+
+
+[,sh]
+----
+                                             Task #1
+┌────────────┬──────────────────────────────────────────────────────────────────────────────────┐
+│         Id │ 1                                                                                │
+├────────────┼──────────────────────────────────────────────────────────────────────────────────┤
+│      Title │ buy milk                                                                         │
+├────────────┼──────────────────────────────────────────────────────────────────────────────────┤
+│     Status │ In progress                                                                      │
+├────────────┼──────────────────────────────────────────────────────────────────────────────────┤
+│   Priority │ Normal                                                                           │
+├────────────┼──────────────────────────────────────────────────────────────────────────────────┤
+│   Category │ personal                                                                         │
+├────────────┼──────────────────────────────────────────────────────────────────────────────────┤
+│ Created at │ 2025-12-09 13:36                                                                 │
+├────────────┼──────────────────────────────────────────────────────────────────────────────────┤
+│    Details │ I want to buy milk because my wife is the boss of me and she told be to buy milk │
+└────────────┴──────────────────────────────────────────────────────────────────────────────────┘
+----
+
+
+If you made a mistake, you can edit a task with
+
+[,sh]
+----
+kanban-cli edit 1
+----
+
+which should show the same sequence of prompts when adding it, except the fields come pre-filled. You can simply press the return key for the ones you don't want to change.
+
+Finally, you can delete a task with
+
+[,sh]
+----
+kanban-cli delete 1
+----
+
+which removes it *forever* from the data.
+
+You can manipulate the categories with similar commands by replacing `tasks` with `categories`.
+
+== Getting help
+
+For general help on the full commands, type
+
+[,sh]
+----
+kanban-cli --help
+----
+
+and it will show all available options and commands, like as follows:
+
+[,sh]
+----
+ Simple Kanban management in the command line
+
+╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --filename            -f      TEXT  File name [default: kanban.db]                                                                  │
+│ --install-completion                Install completion for the current shell.                                                       │
+│ --show-completion                   Show completion for the current shell, to copy it or customize the installation.                │
+│ --help                              Show this message and exit.                                                                     │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ tasks                                                                                                                               │
+│ categories                                                                                                                          │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+----
 
-TODO
+Also, for a given command, you can get further help, for instance,
+
+[,sh]
+----
+kanban-cli tasks --help
+----
+
+== Customizing the settings
+
+The library has the following config variables with their default values:
+
+[,toml]
+----
+db_name = "kanban.db"
+task__title_max_length = 50
+category__name_max_length = 50
+statuses = ["To-do", "In progress", "Review", "Done"]
+priorities = ["Lowest", "Low", "Normal", "High", "Highest"]
+----
+
+You can change some or all of them in two different ways.
+
+=== Using environment variables
+
+You can create an environment variable in your shell with any of the previous config by (i) putting it in all caps and (ii) preceding it with a `KB_`.
+
+Examples considering a `bash` compatible shell:
+
+* `export KB_TASK__TITLE_MAX_LENGTH=100` will raise the limit on the task title to 100 characters;
+* `export KB_STATUSES=["Backlog", "Doing", "Done"]` will change the possible statuses to these three instead.
+
+[NOTE]
+--
+Of course, different shells may have different ways of assigning these variables (e.g., `fish` shell requires us to write `set -x KB_TASK__TITLE_MAX_LENGTH 100`). Check your shell for that option.
+--
+
+If you change only some variables, the others will retain their default values.
+
+
+=== Using a configuration file
+
+Alternatively, you can create a `kb_settings.toml` file in you current directory and update only the variables you want. In this case, you don't need to use capitalized letters neither append `KB_` to them.
+
+For example, you can get the previous configuration variables by creating a `kb_settings.toml` file with:
+
+[,toml]
+----
+task__title_max_length = 100
+statuses = ["Backlog", "Doing", "Done"]
+----
+
+and, as before, unset variables retain their default values.
+
+Keep in mind that, if you use both approaches at the same time, the environment variables take precedence.
+
+[TIP]
+--
+The `db_name` is the only one that has a corresponding command line option with `--filename` or just `-f` in case you want to handle multiple files without having to deal with env variables or settings files.
+--
+
+[NOTE]
+--
+Keep in mind that you should avoid changing the config files to existing files, as the tasks may have been created with the old configuration.
+
+Hence, always start a new tasks file if changing the configuration.
+--
 
 
 == For developers
 
+The library uses https://github.com/astral-sh/uv[`uv`] as project manager. Make sure it is installed in your system.
+
+Then, install all dependencies with:
+
+[,sh]
+----
+uv sync
+----
+
 Before creating a pull request, make sure the following conditions are satisfied:
 
 [,sh]

diff --git a/README_PYPI.md b/README_PYPI.md
@@ -0,0 +1,40 @@
+# Kanban cli management
+
+This is a command-line tool to manage simple kanban boards.
+
+## Installation
+
+The recommended way is to use [`pipx`](https://pypi.org/project/pipx), which installs the software in a separate Python environment automatically without you needing to worry about Python at all:
+
+```sh
+pipx install py-kanban-cli
+```
+
+You also don't need sudo privileges here.
+
+Alternatively, if you have a specific Python environment that is active, a simple `pip install` should work as well:
+
+```sh
+pip install py-kanban-cli
+```
+
+## Usage
+
+Notice that, despite the awkward package name `py-kanban-cli`, the cli command is simply `kanban-cli`.
+
+For general help on the full commands, type
+
+```sh
+kanban-cli --help
+```
+
+and it will show all available options and commands.
+
+The most common involve management of tasks and categories, which you can get more details with the following:
+
+```sh
+kanban-cli tasks --help
+kanban-cli categories --help
+```
+
+See the [repository page](https://github.com/fillipe-gsm/kanban-cli) for more complete examples and configuration.
diff --git a/main.py b/main.py
@@ -1,4 +1,4 @@
-from src.app.app import create_app
+from kanban_cli.app.app import create_app
 
 
 def main():

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,8 +1,9 @@
 [project]
-name = "kanban-cli"
-version = "0.1.0"
-description = "Add your description here"
-readme = "README.md"
+name = "py-kanban-cli"
+version = "0.1.4"
+description = "Personal kanban management in command line"
+authors = [{name = "Fillipe Goulart", email="fillipe.gsm@tutanota.com"}]
+readme = "README_PYPI.md"
 requires-python = ">=3.9"
 dependencies = [
     "dynaconf>=3.2.11",
@@ -12,6 +13,14 @@ dependencies = [
     "typer>=0.19.2",
 ]
 
+[project.urls]
+Homepage = "https://github.com/fillipe-gsm/kanban-cli"
+Repository = "https://github.com/fillipe-gsm/kanban-cli"
+Issues = "https://github.com/fillipe-gsm/kanban-cli/issues"
+
+[project.scripts]
+kanban-cli = "kanban_cli.app.app:run_app"
+
 [dependency-groups]
 dev = [
     "ipdb>=0.13.13",
@@ -53,3 +62,11 @@ exclude_also = [
     # Don't need to test this everytime
     "def __str__",
 ]
+
+[tool.uv.build-backend]
+module-name = "kanban_cli"
+module-root = "src"
+
+[build-system]
+requires = ["uv_build >= 0.9.11, <0.10.0"]
+build-backend = "uv_build"
diff --git a/src/__init__.py → src/kanban_cli/__init__.py b/src/__init__.py → src/kanban_cli/__init__.py
diff --git a/src/app/__init__.py → src/kanban_cli/app/__init__.py b/src/app/__init__.py → src/kanban_cli/app/__init__.py
diff --git a/src/app/app.py → src/kanban_cli/app/app.py b/src/app/app.py → src/kanban_cli/app/app.py
@@ -2,10 +2,12 @@
 
 from typer import Option, Typer
 
-from config import settings
-from src.app.models import db
-from src.categories.categories_app import create_app as create_categories_app
-from src.tasks.tasks_app import create_app as create_tasks_app
+from kanban_cli.app.models import db
+from kanban_cli.categories.categories_app import (
+    create_app as create_categories_app,
+)
+from kanban_cli.config import settings
+from kanban_cli.tasks.tasks_app import create_app as create_tasks_app
 
 
 def create_app() -> Typer:
@@ -21,7 +23,7 @@ def main(
     ) -> None:
         """Simple Kanban management in the command line"""
         # Local import to prevent circular imports
-        from src.tasks.models import MODELS  # noqa: E402
+        from kanban_cli.tasks.models import MODELS  # noqa: E402
 
         db.init(filename)
         db.create_tables(MODELS)
@@ -30,3 +32,8 @@ def main(
     app.add_typer(create_categories_app(), name="categories")
 
     return app
+
+
+def run_app() -> None:
+    app = create_app()
+    app()
diff --git a/src/app/models.py → src/kanban_cli/app/models.py b/src/app/models.py → src/kanban_cli/app/models.py
diff --git a/src/categories/__init__.py → src/kanban_cli/categories/__init__.py b/src/categories/__init__.py → src/kanban_cli/categories/__init__.py
diff --git a/src/categories/categories_app.py → src/kanban_cli/categories/categories_app.py b/src/categories/categories_app.py → src/kanban_cli/categories/categories_app.py
@@ -1,9 +1,13 @@
 from typer import Typer
 
-from src.categories.controllers.add_controller import add_controller
-from src.categories.controllers.delete_controller import delete_controller
-from src.categories.controllers.edit_controller import edit_controller
-from src.categories.controllers.view_all_controller import view_all_controller
+from kanban_cli.categories.controllers.add_controller import add_controller
+from kanban_cli.categories.controllers.delete_controller import (
+    delete_controller,
+)
+from kanban_cli.categories.controllers.edit_controller import edit_controller
+from kanban_cli.categories.controllers.view_all_controller import (
+    view_all_controller,
+)
 
 
 def create_app() -> Typer:

diff --git a/src/categories/controllers/__init__.py → ...an_cli/categories/controllers/__init__.py b/src/categories/controllers/__init__.py → ...an_cli/categories/controllers/__init__.py
diff --git a/src/categories/controllers/add_controller.py → .../categories/controllers/add_controller.py b/src/categories/controllers/add_controller.py → .../categories/controllers/add_controller.py
@@ -1,6 +1,8 @@
-from src.categories.controllers.view_all_controller import view_all_controller
-from src.categories.models.category import Category
-from src.tasks.prompts.category_prompt import CategoryPrompt
+from kanban_cli.categories.controllers.view_all_controller import (
+    view_all_controller,
+)
+from kanban_cli.categories.models.category import Category
+from kanban_cli.tasks.prompts.category_prompt import CategoryPrompt
 
 
 def add_controller() -> None: