npm package: @phumudzo/vawlt
Description: A terminal-based vault for your todos, ideas, and issues
Latest version: 0.7.1

# 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

```bash
npm install -g @phumudzo/vawlt
```

## Quick Start

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

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

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

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

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

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

```bash
# 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.

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

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

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

### Statistics

```bash
vawlt stats
```

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

### Export

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

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

```sql
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

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

```bash
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.).

```bash
# 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.

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

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