Vikunja CLI

A command-line interface for interacting with Vikunja, a to-do list application.

Quick Start

The CLI is a standalone executable. Simply run:

./vikunja --help

Authentication

Before using the CLI, you need to authenticate with your Vikunja instance:

Login

./vikunja auth login --api-url "https://your-vikunja-instance.com/api/v1" --token "your-auth-token"

Configure

./vikunja auth configure --api-url "https://your-vikunja-instance.com/api/v1" --token "your-auth-token"

View Configuration

./vikunja auth show

Your credentials will be saved to ~/.vikunja-cli-config.json in your home directory. The API URL must include /api/v1 and will be validated during login.

Usage

Task Management

List all tasks:

./vikunja task list

List tasks in a specific project:

./vikunja task list --project PROJECT_ID

List tasks with pagination and search (no project filter):

./vikunja task list --page 1 --per-page 50 --search "invoice"

List tasks with sorting and filters (no project filter):

./vikunja task list --sort-by due_date --order-by asc --filter 'done = false' --filter-timezone UTC

Create a new task:

./vikunja task create "My new task" --description "A detailed description" --project PROJECT_ID

Get details of a specific task:

./vikunja task get TASK_ID

Update a task:

./vikunja task update TASK_ID --title "Updated title" --done

Delete a task:

./vikunja task delete TASK_ID

List labels for a task:

./vikunja task labels list TASK_ID

Add or remove a label:

./vikunja task labels add TASK_ID LABEL_ID
./vikunja task labels remove TASK_ID LABEL_ID

Replace labels on a task:

./vikunja task labels set TASK_ID LABEL_ID [LABEL_ID...]

List and manage labels:

./vikunja task labels manage list --search urgent
./vikunja task labels manage create "Urgent" --color #ff0000
./vikunja task labels manage update LABEL_ID --title "High Priority"
./vikunja task labels manage delete LABEL_ID

List assignees for a task:

./vikunja task assignees list TASK_ID

Add or remove an assignee:

./vikunja task assignees add TASK_ID USER_ID
./vikunja task assignees remove TASK_ID USER_ID

Replace assignees on a task:

./vikunja task assignees set TASK_ID USER_ID [USER_ID...]

List comments for a task:

./vikunja task comments list TASK_ID

Create a comment:

./vikunja task comments create TASK_ID "This needs review."

Update or delete a comment:

./vikunja task comments update TASK_ID COMMENT_ID "Updated comment text."
./vikunja task comments delete TASK_ID COMMENT_ID

List task attachments:

./vikunja task attachments list TASK_ID --page 1 --per-page 50

Upload attachments:

./vikunja task attachments upload TASK_ID ./file1.pdf ./file2.png

Get or delete an attachment:

./vikunja task attachments get TASK_ID ATTACHMENT_ID
./vikunja task attachments delete TASK_ID ATTACHMENT_ID

Add or remove task relations:

./vikunja task relations add TASK_ID OTHER_TASK_ID related
./vikunja task relations remove TASK_ID OTHER_TASK_ID related

Bulk update tasks:

./vikunja task bulk update --ids 1,2,3 --done true --priority 3

Update a task position:

./vikunja task position TASK_ID VIEW_ID 1234.5

Project Management

List all projects:

./vikunja project list

Create a new project:

./vikunja project create "My Project" --description "Project description"

Get details of a specific project:

./vikunja project get PROJECT_ID

Update a project:

./vikunja project update PROJECT_ID --title "Updated title"

Delete a project:

./vikunja project delete PROJECT_ID

List views for a project:

./vikunja project views PROJECT_ID

List buckets for a project view:

./vikunja project buckets PROJECT_ID VIEW_ID

List tasks for a project view:

./vikunja project view-tasks PROJECT_ID VIEW_ID

List tasks for a project view bucket:

./vikunja project bucket-tasks PROJECT_ID VIEW_ID BUCKET_ID

List users for a project:

./vikunja project users list PROJECT_ID --search alice

Add, update, or remove a project user:

./vikunja project users add PROJECT_ID alice --permission 1
./vikunja project users update PROJECT_ID USER_ID --permission 2
./vikunja project users remove PROJECT_ID USER_ID

List teams for a project:

./vikunja project teams list PROJECT_ID --search engineering

Add, update, or remove a project team:

./vikunja project teams add PROJECT_ID TEAM_ID --permission 1
./vikunja project teams update PROJECT_ID TEAM_ID --permission 2
./vikunja project teams remove PROJECT_ID TEAM_ID

List, create, or update webhooks:

./vikunja project webhooks list PROJECT_ID
./vikunja project webhooks create PROJECT_ID https://example.com/hook task.created,task.updated
./vikunja project webhooks update PROJECT_ID WEBHOOK_ID task.updated
./vikunja project webhooks delete PROJECT_ID WEBHOOK_ID

List and manage project share links:

./vikunja project shares list PROJECT_ID
./vikunja project shares create PROJECT_ID --name "Client Link" --permission 0 --password secret123
./vikunja project shares get PROJECT_ID SHARE_ID
./vikunja project shares delete PROJECT_ID SHARE_ID

Global Options

• --config PATH: Path to config file (default: ~/.vikunja-cli-config.json)
• --api-url URL: Vikunja API URL (overrides config setting, must include /api/v1)
• --token TOKEN: Authentication token (overrides config setting)

Command Reference

Auth

• vikunja auth login --api-url URL --token TOKEN: Validate and save credentials.
• vikunja auth configure [--api-url URL] [--token TOKEN]: Update saved config.
• vikunja auth show: Display current config.

Tasks

• vikunja task list [--project PROJECT_ID] [--page N] [--per-page N] [--search QUERY] [--sort-by FIELDS] [--order-by DIRECTIONS] [--filter EXPR] [--filter-timezone TZ] [--filter-include-nulls] [--expand FIELDS]
  • Filtering/paging options only apply when --project is not set.
• vikunja task create <title> --project PROJECT_ID [--description DESC] [--done] [--assignee ASSIGNEE_ID] [--due-date YYYY-MM-DD]
• vikunja task get <task_id>
• vikunja task update <task_id> [--title TITLE] [--description DESC] [--done BOOL] [--project PROJECT_ID] [--assignee ASSIGNEE_ID] [--due-date YYYY-MM-DD]
• vikunja task delete <task_id>
• vikunja task labels list <task_id>
• vikunja task labels add <task_id> <label_id>
• vikunja task labels remove <task_id> <label_id>
• vikunja task labels set <task_id> <label_id...>
• vikunja task labels manage list [--page N] [--per-page N] [--search QUERY]
• vikunja task labels manage get <label_id>
• vikunja task labels manage create <title> [--description DESC] [--color #rrggbb]
• vikunja task labels manage update <label_id> [--title TITLE] [--description DESC] [--color #rrggbb]
• vikunja task labels manage delete <label_id>
• vikunja task assignees list <task_id>
• vikunja task assignees add <task_id> <user_id>
• vikunja task assignees remove <task_id> <user_id>
• vikunja task assignees set <task_id> <user_id...>
• vikunja task comments list <task_id>
• vikunja task comments get <task_id> <comment_id>
• vikunja task comments create <task_id> <comment>
• vikunja task comments update <task_id> <comment_id> <comment>
• vikunja task comments delete <task_id> <comment_id>
• vikunja task attachments list <task_id> [--page N] [--per-page N]
• vikunja task attachments get <task_id> <attachment_id>
• vikunja task attachments upload <task_id> <file...>
• vikunja task attachments delete <task_id> <attachment_id>
• vikunja task relations add <task_id> <other_task_id> <relation_kind>
• vikunja task relations remove <task_id> <other_task_id> <relation_kind>
• vikunja task bulk update --ids 1,2 --title "New title" [--done true] [--project PROJECT_ID] [--due-date YYYY-MM-DD] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--priority N] [--percent-done N] [--bucket BUCKET_ID] [--fields field...]
• vikunja task position <task_id> <view_id> <position>

Projects

• vikunja project list
• vikunja project create <title> [--description DESC]
• vikunja project get <project_id>
• vikunja project update <project_id> [--title TITLE] [--description DESC]
• vikunja project delete <project_id>
• vikunja project views <project_id>
• vikunja project buckets <project_id> <view_id>
• vikunja project view-tasks <project_id> <view_id>
• vikunja project bucket-tasks <project_id> <view_id> <bucket_id>
• vikunja project users list <project_id> [--page N] [--per-page N] [--search QUERY]
• vikunja project users add <project_id> <username> [--permission N]
• vikunja project users update <project_id> <user_id> --permission N
• vikunja project users remove <project_id> <user_id>
• vikunja project teams list <project_id> [--page N] [--per-page N] [--search QUERY]
• vikunja project teams add <project_id> <team_id> [--permission N]
• vikunja project teams update <project_id> <team_id> --permission N
• vikunja project teams remove <project_id> <team_id>
• vikunja project webhooks list <project_id> [--page N] [--per-page N]
• vikunja project webhooks create <project_id> <target_url> <events>
• vikunja project webhooks update <project_id> <webhook_id> <events>
• vikunja project webhooks delete <project_id> <webhook_id>
• vikunja project shares list <project_id> [--page N] [--per-page N] [--search QUERY]
• vikunja project shares get <project_id> <share_id>
• vikunja project shares create <project_id> [--name NAME] [--permission N] [--password PASS]
• vikunja project shares delete <project_id> <share_id>

Contributing

Feel free to submit issues and enhancement requests!