ClearHead Examples
This directory contains example .actions files demonstrating various features of the ClearHead format.
Basic Examples
- minimal.actions - Simplest possible action
- with_children.actions - Parent-child action hierarchy
- with_description.actions - Actions with descriptions
- with_priority.actions - Priority levels
- with_context.actions - Context tags
- with_do_date.actions - Scheduled (do) dates and times
- with_completed_date.actions - Completed actions
- with_story.actions - Actions belonging to projects/stories
- with_everything.actions - All optional fields demonstrated
New Features (v2.0)
- with_alias.actions - Action aliases for stable references (
=alias-name) - with_sequential.actions - Sequential children marker (
~) for ordered workflows - with_short_uuid.actions - Short UUID references (8 chars) for predecessors
- with_story_path.actions - Hierarchical story paths (
*work/clearhead/cli) - with_new_features.actions - Comprehensive example combining all new features
Scheduling Note
Recurring schedules are defined in .ics files. .actions examples in this directory represent actions (including generated occurrences), not schedule definitions.
Calendar Export
The export command converts actions with due dates into iCalendar (.ics) format for import into calendar applications. Only actions with @ (do_date_time) are included in the export.
Example Files
- calendar_export_example.actions - Comprehensive demonstration including:
- Multiple scheduled actions suitable for calendar export
- All action states (pending, in-progress, blocked, completed, cancelled)
- Priority mapping, categories, and descriptions
- Mixed work/personal planning examples
Example Usage
# Export all actions with dates to iCalendar format
clearhead export calendar_export_example.actions -o calendar.ics
# Export only open (pending/in-progress/blocked) actions
clearhead export calendar_export_example.actions --open-only -o calendar.ics
# Export to stdout for piping
clearhead export calendar_export_example.actions | less
# Export from stdin
cat calendar_export_example.actions | clearhead export > calendar.ics
Importing to Calendar Apps
Google Calendar:
- Export:
clearhead export inbox.actions -o calendar.ics - Go to Google Calendar → Settings → Import & Export
- Click “Select file from your computer” and choose
calendar.ics - Recurring events will automatically expand in your calendar
Apple Calendar:
- Export:
clearhead export inbox.actions -o calendar.ics - Double-click the
.icsfile - Choose which calendar to import into
Outlook:
- Export:
clearhead export inbox.actions -o calendar.ics - File → Open & Export → Import/Export
- Choose “Import an iCalendar (.ics) or vCalendar file”
Supported Features
The calendar export uses standalone VTODO components and supports:
- Scheduled times -
scheduled_atbecomesDTSTART - Due times -
due_datebecomesDUE - Descriptions - Action descriptions become VTODO descriptions
- Priority - ClearHead priority maps directly to RFC 5545
PRIORITY(1-9) - Categories - Context tags become standard
CATEGORIES - Status - Action state maps through VTODO
STATUS:[ ]NotStarted →NEEDS-ACTION[-]InProgress →IN-PROCESS[=]Blocked/Awaiting →NEEDS-ACTIONplusX-CLEARHEAD-STATUS:blocked[x]Completed →COMPLETED[_]Cancelled →CANCELLED
Example File
See calendar_export_example.actions for a comprehensive demonstration of calendar-exportable actions.
Test Files
- conformance/ - Semantic and byte-level conformance corpus, one scenario per fixture (
parse,diagnostics,archive,syntax); see conformance/README.md - formatting/ - Directory with formatting test cases
- linting/ - Directory with lint rule examples
Queries
The queries/ directory contains examples of SQL queries for filtering actions.