Checkvist

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 = [email protected]
remote_key = YOUR_API_KEY

[work]
username = [email protected]
remote_key = WORK_API_KEY

Common Workflows

Workflow 1: Browse and explore tasks

When user wants to see their Checkvist data:

1. List all checklists to find the right one:

   checkvist-cli lists
   

2. Show tasks in a specific list:

   checkvist-cli tasks get --list-id LIST_ID
   

3. 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:

1. Create parent task:

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

   Note the returned task ID.

2. 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
   

3. 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:

1. View current tasks:

   checkvist-cli tasks get --list-id LIST_ID
   

2. Mark tasks as done:

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

3. 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

1. Check authentication first: Always verify auth status before complex operations
2. Use JSON format for scripting: When processing output programmatically, use --format json
3. Parse task hierarchy: In text format, track indentation to understand parent-child relationships
4. Handle IDs carefully: List IDs, task IDs, and note IDs are all required for operations - keep track of them
5. Regular backups: Encourage users to backup their data periodically
6. 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:

1. Guide them through authentication:

   checkvist-cli auth login
   

   They'll need their Checkvist username and remote API key from https://checkvist.com/auth/profile

2. Verify it works:

   checkvist-cli auth status
   

3. Show their lists:

   checkvist-cli lists
   

4. 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