Metadata-Version: 2.4
Name: obsidian-task-tui
Version: 1.0.0
Summary: Interactive terminal UI for managing Obsidian TaskNotes tasks
Project-URL: Homepage, https://github.com/mharlass/obsidian-task-tui
Project-URL: Repository, https://github.com/mharlass/obsidian-task-tui.git
Project-URL: Issues, https://github.com/mharlass/obsidian-task-tui/issues
Author: Matthias Harlass
License-Expression: MIT
License-File: LICENSE
Keywords: obsidian,tasknotes,tasks,terminal,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
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: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.11
Requires-Dist: python-dateutil~=2.9.0
Requires-Dist: textual>=1.0
Requires-Dist: tzdata>=2024.1
Requires-Dist: watchfiles>=1.0
Description-Content-Type: text/markdown

# Obsidian Task TUI

A keyboard-driven terminal UI for managing [Obsidian](https://obsidian.md)
tasks stored in [TaskNotes](https://github.com/callumalpass/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](https://docs.astral.sh/uv/) and Python 3.11 or newer; uv can
install a compatible Python automatically. Run the app without installing it
permanently:

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

Or install it as a persistent command:

```bash
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:

```bash
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:

```bash
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](https://github.com/mharlass/obsidian-task-tui/blob/main/config.example.toml)
for every setting. A minimal config looks like this:

```toml
[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`](https://github.com/mharlass/obsidian-task-tui/tree/main/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

```bash
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](https://github.com/mharlass/obsidian-task-tui/blob/main/RELEASING.md)
for the PyPI release process.

## License

Released under the [MIT License](https://github.com/mharlass/obsidian-task-tui/blob/main/LICENSE).
