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:

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

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

checkvist-cli lists create "List Name"

Update a list:

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

checkvist-cli lists delete LIST_ID

Show list details:

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

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

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

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

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:

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:

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

Update a note:

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

Delete a note:

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

5. Backup

Export all checklists to OPML format:

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

12345	My Checklist Name
67890	Another Checklist

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

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

JSON Format

Use --format json for programmatic processing:

checkvist-cli --format json lists get

Returns structured JSON with descriptive keys:

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

Profiles

Support for multiple Checkvist accounts via profiles:

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

[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:
```
checkvist-cli lists
```

Show tasks in a specific list:

checkvist-cli tasks get --list-id LIST_ID

If user wants to see notes on a specific task:

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:

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

Note the returned task ID.

Create subtasks:

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:

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:

checkvist-cli tasks get --list-id LIST_ID

Mark tasks as done:

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

Update task content if needed:

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:

# 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:
```
checkvist-cli auth login
```
They'll need their Checkvist username and remote API key from https://checkvist.com/auth/profile
Verify it works:
```
checkvist-cli auth status
```
Show their lists:
```
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

checkvist

SKILL.mdclaude/skills/checkvist