obsidian-task-tui 1.0.0

Interactive terminal UI for managing Obsidian TaskNotes tasks

Obsidian Task TUI

A keyboard-driven terminal UI for managing Obsidian tasks stored in TaskNotes format. It works directly on Markdown files, stays usable without Obsidian running, and refreshes when files change.

Highlights

• Browse, sort, create, edit, complete, and delete tasks without leaving the terminal.
• Use any TaskNotes status workflow; categories are discovered from the vault or the TaskNotes plugin configuration.
• Preserve custom status values, priorities, tags, and unrecognized frontmatter.
• Complete recurring instances without closing the recurring task itself.
• Enter dates as ISO values or shortcuts such as tomorrow, +3d, and next mon.
• Choose dark, light, and colorblind-friendly themes in a responsive interface.
• Keep Obsidian edits in sync through live file watching.

Install and run

Requires uv and Python 3.11 or newer; uv can install a compatible Python automatically. Run the app without installing it permanently:

uvx obsidian-task-tui --vault /path/to/your/vault

Or install it as a persistent command:

uv tool install obsidian-task-tui
obsidian-task-tui --vault /path/to/your/vault

If the installed command is not on PATH, run uv tool update-shell once and restart the shell. Pin a release with uvx obsidian-task-tui@1.0.0 --vault /path/to/your/vault or uv tool install obsidian-task-tui@1.0.0. The legacy obsidian-tasks command remains available after installation.

To run the latest unreleased GitHub version instead:

uvx --from git+https://github.com/mharlass/obsidian-task-tui obsidian-task-tui \
  --vault /path/to/your/vault

Usage

Pass a vault root, a TaskNotes directory, or configure a default:

obsidian-task-tui --vault ~/Documents/my-vault
obsidian-task-tui --tasks-dir ~/Documents/my-vault/TaskNotes/Tasks
obsidian-task-tui --config ~/.config/obsidian-task-tui/config.toml
obsidian-task-tui --theme github-dark-colorblind

Option	Purpose	Default
--vault PATH	Obsidian vault root	~/Documents/work
--tasks-dir PATH	TaskNotes task directory	TaskNotes setting or <vault>/TaskNotes/Tasks
--config PATH	TOML configuration file	~/.config/obsidian-task-tui/config.toml
--theme THEME	dark, light, obsidian-night, github-dark-colorblind, or github-light-colorblind	Config value or dark
--version	Print the installed version

For applicable settings, precedence is CLI arguments, environment variables, the TUI config file, TaskNotes data.json, task-file discovery, then built-in defaults. Supported environment variables are OBSIDIAN_VAULT_PATH, OBSIDIAN_TASKS_DIR, OBSIDIAN_TASK_TUI_CONFIG, and OBSIDIAN_TASK_TUI_THEME. The selected task directory must already exist and be writable. --tasks-dir selects files directly; also pass --vault if the app should load that vault's TaskNotes plugin metadata.

Configuration and TaskNotes compatibility

The config file is optional; --vault is enough for most users. See the complete example for every setting. A minimal config looks like this:

[paths]
vault_path = "/path/to/your/vault"

[tasks]
task_tag = "task"

[ui]
theme = "dark"
table_categories = ["backlog", "doing", "done"]
default_status = "backlog"

[status_values] # exact vault status -> built-in semantic role
done = "complete"

When .obsidian/plugins/tasknotes/data.json exists, the app reads its task folder, task tag, category order, labels, colors, completed categories, and default status. The built-in task tag is task. Task files add previously unseen statuses; an entirely custom workflow can replace the built-in tabs through discovery.

Arbitrary status values work without mapping. In [status_values], each key is an exact vault status and each value is a built-in semantic role: complete enables completion fields, recurring enables per-instance completion, and task-pile selects the preferred reopen destination. The x shortcut writes the exact status of the first complete category in tab order, so configure one completion destination when possible. Use [priority_values] when the vault has custom priority names. Without plugin metadata or overrides, the default statuses are recurring, task-pile, to-do-week, in-progress-today, In-progress, and complete. Status values are case-sensitive.

Task notes need YAML frontmatter with a non-empty status and the configured task tag; standard TaskNotes property names such as status, priority, and due are expected. The app loads matching top-level .md files. Files it cannot parse are left untouched and skipped, with an in-app warning when the error can be identified. When rewriting a task, the parser preserves unknown top-level fields, nested or multiline frontmatter, unmapped values, and note bodies. A runnable custom-vault example is available in examples/other-vault.

Completing a recurring task toggles the current date in complete_instances. Deleting with D permanently removes the underlying Markdown file after confirmation, so keep the vault backed up or under version control.

Scheduled and due dates accept YYYY-MM-DD, today, tomorrow, yesterday, signed day offsets such as +3d, and weekdays such as next tuesday. In a focused date field, ↑ and ↓ move the date by one day.

Keyboard shortcuts

Key	Action
Tab / Shift+Tab	Next / previous status tab
j / k or ↓ / ↑	Select the next / previous task
Enter	Open task details
n	Create a task
e	Edit the open task
Ctrl+S	Save a created or edited task
Escape	Cancel or go back
1–5	Move the task to the corresponding displayed category
x	Complete the task or the current recurring instance
D	Delete the selected task after confirmation
s	Cycle the table sort
t	Cycle the theme
r	Reload tasks from disk
?	Open help
q	Quit or return from details

Number keys cover the first five categories; open and edit a task to select any additional category.

Development

git clone https://github.com/mharlass/obsidian-task-tui.git
cd obsidian-task-tui
uv sync --all-groups --locked
uv run ruff check .
uv run ruff format .
uv run pytest -q
uv build --no-sources

See RELEASING.md for the PyPI release process.

License

Released under the MIT License.