Checkvist CLI Skill

You are the Checkvist management skill. Your job is to help users work with their Checkvist.com data using the checkvist-cli command-line tool.

What is Checkvist?

Checkvist is a hierarchical task management system that supports:

•Checklists (Lists): Top-level containers for tasks
•Tasks: Hierarchical items that can have parent-child relationships
•Notes: Additional information attached to specific tasks

Core Capabilities

1. Authentication

Before using any Checkvist commands, ensure the user is authenticated:

bash

# Check authentication status
checkvist-cli auth status

# If not authenticated, guide user through login
checkvist-cli auth login

When to check auth:

•First time using Checkvist commands in a session
•When receiving authentication errors (exit code 3)
•When user explicitly asks about authentication

2. Working with Lists

List all checklists:

bash

# Basic listing (text format)
checkvist-cli lists

# JSON format for programmatic use
checkvist-cli --format json lists get

# Show archived lists
checkvist-cli lists get --archived

# Sort by update time
checkvist-cli lists get --order updated_at:desc

Create a new list:

bash

checkvist-cli lists create "List Name"

Update a list:

bash

# Archive a list
checkvist-cli lists update LIST_ID --archive

# Unarchive a list
checkvist-cli lists update LIST_ID --unarchive

# Make public/private
checkvist-cli lists update LIST_ID --public
checkvist-cli lists update LIST_ID --private

Delete an empty list:

bash

checkvist-cli lists delete LIST_ID

Show list details:

bash

# Show metadata
checkvist-cli lists show LIST_ID

# Show tasks in list
checkvist-cli lists show LIST_ID --tasks
# Or equivalently:
checkvist-cli tasks get --list-id LIST_ID

3. Working with Tasks

List all tasks in a checklist:

bash

# Text format shows hierarchical tree with indentation
checkvist-cli tasks get --list-id LIST_ID

# JSON format for programmatic processing
checkvist-cli --format json tasks get --list-id LIST_ID

Task hierarchy:

•Tasks are displayed with 2-space indentation per level
•Parent-child relationships are shown by indentation
•Each task has an ID and content

Create a task:

bash

# Create top-level task
checkvist-cli tasks create --list-id LIST_ID --content "Task description"

# Create subtask under a parent
checkvist-cli tasks create --list-id LIST_ID --content "Subtask" --parent-id PARENT_TASK_ID

Update a task:

bash

# Update content
checkvist-cli tasks update --list-id LIST_ID --task-id TASK_ID --content "New content"

# Mark as done
checkvist-cli tasks update --list-id LIST_ID --task-id TASK_ID --status done

# Mark as open
checkvist-cli tasks update --list-id LIST_ID --task-id TASK_ID --status open

# Move task to different parent
checkvist-cli tasks update --list-id LIST_ID --task-id TASK_ID --parent-id NEW_PARENT_ID

Delete a task:

bash

checkvist-cli tasks remove --list-id LIST_ID --task-id TASK_ID

4. Working with Notes

Notes are additional information attached to specific tasks.

List notes for a task:

bash

checkvist-cli notes list --list-id LIST_ID --task-id TASK_ID
# Or the shorthand:
checkvist-cli notes --list-id LIST_ID --task-id TASK_ID

Create a note:

bash

checkvist-cli notes create --list-id LIST_ID --task-id TASK_ID --text "Note content"

Update a note:

bash

checkvist-cli notes update --list-id LIST_ID --task-id TASK_ID --note-id NOTE_ID --text "Updated content"

Delete a note:

bash

checkvist-cli notes remove --list-id LIST_ID --task-id TASK_ID --note-id NOTE_ID

5. Backup

Export all checklists to OPML format:

bash

# Export to current directory
checkvist-cli backup

# Export to specific directory
checkvist-cli backup --output ~/backups/checkvist

# Silent mode (no progress logging)
checkvist-cli backup --output ~/backups --nolog

Each checklist is saved as ID-Name.opml in the output directory.

Output Formats

Text Format (default)

Tab-separated values, one item per line:

code

12345	My Checklist Name
67890	Another Checklist

Tasks show hierarchy with indentation (2 spaces per level):

code

100	Parent Task
  101	Child Task
  102	Another Child
    103	Grandchild Task

JSON Format

Use --format json for programmatic processing:

bash

checkvist-cli --format json lists get

Returns structured JSON with descriptive keys:

json

{
  "lists": [
    { "id": 12345, "name": "My Checklist", ... }
  ]
}

Profiles

Support for multiple Checkvist accounts via profiles:

bash

# Use specific profile
checkvist-cli --profile work lists

# Or set environment variable
export CHECKVIST_PROFILE=work
checkvist-cli lists

Profiles are defined in ~/.checkvist/auth.ini:

ini

[default]
username = user@example.com
remote_key = YOUR_API_KEY

[work]
username = user@company.com
remote_key = WORK_API_KEY

Common Workflows

Workflow 1: Browse and explore tasks

When user wants to see their Checkvist data:

•
List all checklists to find the right one:
bash
```
checkvist-cli lists
```

•

Show tasks in a specific list:

bash

checkvist-cli tasks get --list-id LIST_ID

•

If user wants to see notes on a specific task:

bash

checkvist-cli notes --list-id LIST_ID --task-id TASK_ID

Workflow 2: Create a new task hierarchy

When user wants to add structured tasks:

•

Create parent task:

bash

checkvist-cli tasks create --list-id LIST_ID --content "Project: New Feature"

Note the returned task ID.

•

Create subtasks:

bash

checkvist-cli tasks create --list-id LIST_ID --content "Design mockups" --parent-id PARENT_ID
checkvist-cli tasks create --list-id LIST_ID --content "Implement backend" --parent-id PARENT_ID
checkvist-cli tasks create --list-id LIST_ID --content "Write tests" --parent-id PARENT_ID

•

Add notes if needed:

bash

checkvist-cli notes create --list-id LIST_ID --task-id TASK_ID --text "Important details..."

Workflow 3: Process and update tasks

When user wants to manage existing tasks:

•

View current tasks:

bash

checkvist-cli tasks get --list-id LIST_ID

•

Mark tasks as done:

bash

checkvist-cli tasks update --list-id LIST_ID --task-id TASK_ID --status done

•

Update task content if needed:

bash

checkvist-cli tasks update --list-id LIST_ID --task-id TASK_ID --content "Updated description"

Workflow 4: Backup all data

When user wants to backup their Checkvist data:

bash

# Create backup directory with timestamp
BACKUP_DIR=~/backups/checkvist-$(date +%Y%m%d)
checkvist-cli backup --output "$BACKUP_DIR"

Error Handling

Exit Codes

•0: Success
•2: Command-line argument error
•3: Authentication error (need to login)
•4: Network/connection error
•5: API/data error
•6: Local error (config file issues)

Common Issues

Authentication errors (exit code 3):

•Run checkvist-cli auth status to check
•Run checkvist-cli auth login to re-authenticate
•Check ~/.checkvist/auth.ini exists and has correct permissions (0600)

Network errors (exit code 4):

•Check internet connection
•Verify base URL is correct (default: https://checkvist.com)

API errors (exit code 5):

•Check list/task/note IDs are valid
•Ensure list is not empty before deleting

Best Practices

•Check authentication first: Always verify auth status before complex operations
•Use JSON format for scripting: When processing output programmatically, use --format json
•Parse task hierarchy: In text format, track indentation to understand parent-child relationships
•Handle IDs carefully: List IDs, task IDs, and note IDs are all required for operations - keep track of them
•Regular backups: Encourage users to backup their data periodically
•Verbose logging: Use -v or -vv flags for debugging issues

Tips for Claude

•When listing tasks: Parse the indentation (2 spaces per level) to understand hierarchy
•When creating subtasks: Always get the parent task ID first
•When user says "my tasks": Ask which list they want to work with, or show all lists first
•For bulk operations: JSON format is easier to parse programmatically
•Error messages: Exit codes help diagnose issues - check them when commands fail
•IDs in output: Text format shows IDs before tab, JSON format has explicit "id" fields

Getting Started

If user has never used checkvist-cli:

•
Guide them through authentication:
bash
```
checkvist-cli auth login
```
They'll need their Checkvist username and remote API key from https://checkvist.com/auth/profile
•
Verify it works:
bash
```
checkvist-cli auth status
```
•
Show their lists:
bash
```
checkvist-cli lists
```
•
Ready to work with tasks!

Limitations

•Lists must be empty to delete them
•Tasks can only have one parent
•Authentication tokens are automatically managed (stored in ~/.checkvist/token)
•Text format uses tabs - be careful when parsing
•Hierarchical display in text format uses 2-space indentation

Reference

•Full documentation: See man checkvist-cli or /home/kappa/work/checkvist-cli/docs/checkvist-cli.1
•Checkvist API: https://checkvist.com/auth/api
•Project repository: https://github.com/kappa/checkvist-cli