vikunja-kanban

No summary provided.

Vikunja Kanban Skill

Manage a Vikunja kanban board via API. Read status, create/move/complete tasks, and integrate with heartbeat and triage crons.

Config

Credentials stored in secrets/vikunja.env:

text

VIKUNJA_URL=https://kanban.pigpen.haus
VIKUNJA_TOKEN=${VIKUNJA_TOKEN}
VIKUNJA_PROJECT_ID=1
VIKUNJA_VIEW_ID=4

Authentication

All scripts use a long-lived API token (expires 2030-01-01). No JWT login needed.

• Token: Set via VIKUNJA_TOKEN environment variable
• Permissions: tasks (read_all, update, create, delete), projects (read_all, update, create)
• Header: Authorization: Bearer $VIKUNJA_TOKEN
• JWT login credentials kept in secrets/vikunja.env for reference only

Bucket IDs

ID	Name	Purpose
1	🔴 Urgent	Needs immediate attention
2	⏳ Waiting On	Sent/requested, awaiting reply
7	⚠️ System Issues	Infra/system problems
8	🚧 Active Projects	In progress
9	📅 Upcoming	Scheduled/future
10	📥 Inbox	New items, untriaged
3	✅ Done	Completed

Scripts

All scripts are in the skill's scripts/ directory. Run from the skill root.

Read the board

bash

bash scripts/vikunja-status.sh              # All buckets
bash scripts/vikunja-status.sh "Urgent"     # Filter by bucket name

Add a task

bash

bash scripts/vikunja-add-task.sh "Title" "Description" BUCKET_ID [PRIORITY]
# Priority: 0=unset, 1=low, 2=medium, 3=high, 4=urgent
# Example: bash scripts/vikunja-add-task.sh "Fix DNS" "Check records" 1 4

Move a task between buckets

bash

bash scripts/vikunja-move-task.sh TASK_ID BUCKET_ID
# Example: bash scripts/vikunja-move-task.sh 15 3  # Move to Done

Complete a task

bash

bash scripts/vikunja-complete-task.sh TASK_ID

Heartbeat Integration

The heartbeat cron reads from Vikunja:

bash

bash scripts/vikunja-status.sh

• Check 🔴 Urgent for items aging >1h
• If Vikunja unreachable, fall back to scripts/nc-status-board.sh read

Email Triage Integration

Email triage adds Action Required items to the Inbox bucket:

bash

bash scripts/vikunja-add-task.sh "Email subject" "Brief description" 10 3

API Reference

• Base URL: https://kanban.pigpen.haus/api/v1
• Auth: POST /login with username/password → JWT token (short-lived)
• Tasks: PUT /projects/{id}/tasks (create), POST /tasks/{id} (update)
• Buckets: POST /projects/{id}/views/{view}/buckets/{bucket}/tasks (move task)
• Views: GET /projects/{id}/views/{view}/tasks (list tasks by bucket)

Notes

• Long-lived API token used (expires 2030) — no JWT login overhead
• Vikunja uses PUT for creation, POST for updates (unusual)
• Bucket IDs are specific to the Kanban view (view_id=4)
• Project is shared: Kit (admin), Alex (user)
• Token has tasks + projects permissions; covers all kanban operations