Skip to content

Your First Task

This guide will walk you through creating and managing your first task with TaskRepo.

Initialization

Before creating tasks, initialize TaskRepo:

tsk init

This creates a configuration file at ~/.TaskRepo/config and sets up the parent directory for task repositories (default: ~/tasks).

Create a Repository

Tasks are organized into repositories. Create your first repository:

tsk create-repo work

This creates a tasks-work directory with git initialization. You can create multiple repositories for different contexts:

tsk create-repo personal
tsk create-repo opensource

List your repositories:

tsk repos

Add Your First Task

The easiest way to add a task is using interactive mode:

tsk add

You'll be prompted for:

  • Repository: Select from your available repositories
  • Title: Brief description of the task
  • Status: pending, in-progress, completed, cancelled
  • Priority: H (High), M (Medium), L (Low)
  • Project: Optional project name
  • Assignees: GitHub handles (e.g., @alice)
  • Tags: Comma-separated tags
  • Due date: Natural language (e.g., "tomorrow", "next week", "2025-11-15")
  • Description: Full task description (opens in your editor)

Non-Interactive Mode

You can also create tasks with command-line flags:

tsk add -r work \
  -t "Fix authentication bug" \
  -p backend \
  --priority H \
  --assignees @alice,@bob \
  --tags bug,security \
  --due "next week"

Associate URLs with your task (GitHub issues, emails, documentation):

tsk add -r work \
  -t "Fix authentication bug" \
  --links https://github.com/org/repo/issues/123,https://docs.example.com/auth

View Your Tasks

List all tasks:

tsk list

Filter by repository:

tsk list --repo work

Filter by status and priority:

tsk list --status pending --priority H

Show completed tasks:

tsk list --all

Mark Task as Done

Complete a task by its ID:

tsk done 1

You can complete multiple tasks at once:

tsk done 1 2 3
# Or
tsk done 1,2,3

Edit a Task

Edit an existing task:

tsk edit 1

This opens the task file in your editor. You can edit: - The YAML frontmatter (metadata) - The markdown description

Search Tasks

Search for tasks by text:

tsk search "authentication"

Search supports filters:

tsk search "bug" --priority H --repo work

Interactive TUI

Launch the interactive Terminal User Interface:

tsk tui

TaskRepo TUI Interface

The TUI provides a rich visual interface with:

Navigation:

  • ↑/↓ Arrow keys - Move between tasks
  • Tab - Switch between repositories
  • / - Filter tasks

Operations:

  • Space - Select/deselect tasks (multi-select)
  • Enter - Mark selected task(s) as done
  • e - Edit selected task
  • d - Delete selected task
  • p - Mark as in-progress
  • c - Mark as cancelled
  • a - Archive completed tasks
  • m - Move tasks to different repository
  • s - Sync with git
  • t - Toggle tree view
  • q - Quit

Task Details Panel:

The bottom panel shows complete details for the selected task including:

  • Repository, project, status, and priority
  • Creation and modification timestamps
  • Assigned users and tags
  • Due date with countdown
  • Associated links (GitHub issues, documentation, etc.)

Sync with Git

Sync your tasks with a git remote:

# Sync all repositories
tsk sync

# Sync specific repository
tsk sync --repo work

# Pull only (don't push)
tsk sync --no-push

What You've Learned

You now know how to:

  • ✅ Initialize TaskRepo
  • ✅ Create repositories
  • ✅ Add tasks (interactive and non-interactive)
  • ✅ List and filter tasks
  • ✅ Mark tasks as done
  • ✅ Edit tasks
  • ✅ Search tasks
  • ✅ Use the TUI
  • ✅ Sync with git

Next Steps