vawlt

A terminal-based vault for tracking your todos, ideas, and issues. Supports both global (user-wide) and local (per-project) journals backed by SQLite.

Installation

npm install -g @phumudzo/vawlt

Quick Start

# Add entries
vawlt todo "Write documentation" --due 2026-04-10 --priority high
vawlt idea "Build a meal prep app"
vawlt issue "Login button not working" --priority medium

# List and filter
vawlt list
vawlt list --type todo --status pending

# Manage status
vawlt start 1
vawlt done 1

# Search
vawlt search "auth"

Features

• Three entry types: todos, ideas, and issues
• Status tracking: pending, in-progress, done
• Priority levels: low, medium, high
• Tags: organize entries with custom tags
• Due dates: with smart relative parsing (tomorrow, next-week, etc.)
• Full-text search: powered by SQLite FTS5
• Statistics: track your productivity
• Export: JSON, Markdown, and CSV
• Global + local: user-wide journal and per-project journals
• Subtasks: break todos into checklists with progress tracking
• Recurring todos: auto-recreate daily, weekly, or monthly when completed
• Reminders: overdue and due-today warnings shown after every command
• Issue workflow: due dates, severity, kind, resolution, links, and issue reminders
• Zero config: works out of the box, data stored in ~/.vawlt/

Commands

Adding Entries

# Add a todo
vawlt todo "Implement auth module" --due 2026-04-15 --priority high --tag backend

# Add an idea
vawlt idea "Dark mode support" --tag ui --tag design

# Add an issue
vawlt issue "Memory leak in worker" --priority high --severity critical --kind incident --due tomorrow --tag bug

# Interactive mode (omit content to be prompted)
vawlt todo

Use -l or --local on any command to use the local project journal instead of the global one.

Listing Entries

vawlt list                              # all entries
vawlt list --type todo                  # only todos
vawlt list --status pending             # by status
vawlt list --tag backend                # by tag
vawlt list --due-today                  # due today
vawlt list --due-week                   # due within 7 days
vawlt list --due-month                  # due this month
vawlt list --overdue                    # past due date
vawlt list --type issue --severity critical
vawlt list --type issue --kind bug

Status Management

vawlt start <id>                        # mark any entry as in-progress
vawlt done <id>                         # mark any entry as done
vawlt pending <id>                      # mark any entry as pending

Editing Entries

vawlt edit <id> --content "Updated text"
vawlt edit <id> --priority high --due 2026-05-01
vawlt edit <id> --status done
vawlt edit <id> --tag newtag --tag anothertag
vawlt edit <id> --severity critical --kind bug --resolution fixed

Deleting Entries

vawlt delete <id>                       # with confirmation prompt
vawlt delete <id> --force               # skip confirmation

Subtasks

Break a todo or issue into smaller checklist items with a visual progress bar.

# Add subtasks to a todo or issue
vawlt subtask add <entry-id> "Write unit tests"
vawlt subtask add <entry-id> "Update docs"
vawlt subtask add <entry-id> "Deploy to staging"

# View subtasks with progress bar
vawlt subtask list <entry-id>
#  Todo #1: Implement auth module
#  ████████████░░░░░░░░ 67% (2/3)
#
#  [x] #1 Write unit tests
#  [x] #2 Update docs
#  [ ] #3 Deploy to staging

# Toggle a subtask done/undone
vawlt subtask check <subtask-id>

# Remove a subtask
vawlt subtask remove <subtask-id>

Recurring Todos

Set todos to automatically recreate when completed.

# Create a recurring todo (must have a due date)
vawlt todo "Weekly review" --due next-week --repeat weekly

# Or set recurrence on an existing todo
vawlt repeat <id> daily
vawlt repeat <id> weekly
vawlt repeat <id> monthly

# Remove recurrence
vawlt repeat <id> --off

# When you mark a recurring todo as done, the next one is auto-created:
vawlt done 1
# ✓ Entry #1 marked as done
# ↻ Recurring weekly todo recreated as #2 (due 2026-04-10)

Reminders

Overdue and due-today todos are automatically shown after every command:

  ─── reminders ───────────────────────
  ! 2 overdue todos
    #3 Submit report (due 2026-03-28) !!
    #5 Review PR (due 2026-04-01)
  ~ 1 todo due today
    #7 Team standup
  ─────────────────────────────────────

Issues with due dates also appear in reminders, including stronger markers for critical severity. Reminders check both global and local journals.

Issue Workflow

# Create rich issues
vawlt issue "Checkout fails on iOS" --kind bug --severity critical --priority high --due tomorrow

# Update issue classification and resolution
vawlt edit <issue-id> --kind incident --severity high
vawlt edit <issue-id> --status done --resolution fixed

# Link related issues
vawlt issue-link add <issue-id> <other-issue-id> blocked-by
vawlt issue-link add <issue-id> <other-issue-id> duplicate-of
vawlt issue-link add <issue-id> <other-issue-id> relates-to
vawlt issue-link list <issue-id>
vawlt issue-link remove <link-id>

Search

vawlt search "authentication"
vawlt search "refactor" --type todo

Statistics

vawlt stats

Displays total entries by type, todo completion rate, status breakdown, priority distribution, recent activity, and overdue count.

Export

vawlt export                            # JSON to stdout
vawlt export --format markdown          # Markdown to stdout
vawlt export --format csv               # CSV to stdout
vawlt export --format json -o backup.json  # write to file

Project Setup

# Initialize a local journal in the current directory
vawlt init

# Show database path and info
vawlt path
vawlt path --local

Running vawlt init creates a .vawlt/ directory and automatically adds it to .gitignore if you're in a git repo.

Storage

| Scope | Location | Flag | |--------|------------------------|------------| | Global | ~/.vawlt/vawlt.db | (default) | | Local | .vawlt/vawlt.db | -l / --local |

Both use SQLite with full-text search (FTS5). The local journal is found by searching up the directory tree for a .vawlt/ folder, similar to how git finds .git/.

Database Schema

CREATE TABLE entries (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    type TEXT NOT NULL CHECK(type IN ('todo', 'idea', 'issue')),
    content TEXT NOT NULL,
    status TEXT CHECK(status IN ('pending', 'in-progress', 'done', NULL)),
    priority TEXT CHECK(priority IN ('low', 'medium', 'high', NULL)),
    due_date TEXT,
    tags TEXT,
    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);

Examples

Personal Task Management

vawlt todo "Buy groceries" --due tomorrow --priority high
vawlt todo "Call dentist" --priority medium
vawlt idea "Build a meal prep app"
vawlt list --type todo --status pending
vawlt start 1
vawlt done 1
vawlt stats

Project Tracking

cd my-project
vawlt init
vawlt -l issue "Login button not responding on mobile"
vawlt -l todo "Write unit tests for auth module" --priority high
vawlt -l idea "Add dark mode support"
vawlt list --local
vawlt search "auth" --local
vawlt export --local --format markdown -o PROJECT_JOURNAL.md

Non-Interactive / Agent Mode

vawlt is fully usable by AI agents, scripts, and CI pipelines.

--no-input

Disables all interactive prompts. Commands will error with a helpful message if required arguments are missing instead of waiting for stdin. This is also auto-enabled when stdin is not a TTY (piped input, CI, etc.).

# These work — all args provided as flags
vawlt --no-input todo "Deploy to prod" --due tomorrow --priority high
vawlt --no-input edit 1 --content "Updated text" --status done
vawlt --no-input delete 3 --force

# This errors instead of hanging
vawlt --no-input todo
# error: Interactive input required but --no-input is set...

--json

Returns structured JSON output instead of colorized human-readable text. Reminders are suppressed in JSON mode.

# Add and get back the ID
vawlt --json todo "Fix auth bug" --priority high
# {"ok":true,"id":5,"type":"todo","content":"Fix auth bug",...}

# List all entries as JSON array
vawlt --json list
# {"ok":true,"count":10,"entries":[...]}

# Get stats as structured data
vawlt --json stats
# {"ok":true,"total":10,"todos":7,"ideas":2,...}

# Search returns matching entries
vawlt --json search "auth"
# {"ok":true,"query":"auth","count":2,"entries":[...]}

# Status changes include recurrence info
vawlt --json done 5
# {"ok":true,"id":5,"status":"done","recurred":{"id":6,"due_date":"2026-04-10"}}

Combining Both

For full agent compatibility, use both flags together:

vawlt --no-input --json todo "Agent task" --due tomorrow --priority high
vawlt --no-input --json list --type todo --status pending
vawlt --no-input --json done 5
vawlt --no-input --json delete 3 --force

Requirements

• Node.js >= 16

License

MIT