Commands (Alphabetical)

Usage: add <item_to_add> to <target_template> [position:<number>]
Description: Adds an item to a template, intelligently resolving ambiguity.
Example: add "My Subroutine" to "My Routine" position:1

Usage: append <item_type> <item_name> "<text_to_append>" [property_key:property_value ...]
Description: Appends text to the content of an existing item.
Example: append note MyMeetingNotes "- Discuss Q3 results"

Usage: change <item_name> <new_start_time_HH:MM>
Description: Changes the start time of an item in the current day's schedule.
Example: change "Morning Routine" 08:30

Usage: cls
Description: Clears the terminal screen.
Example: cls

Usage: cmd <command>
Description: Executes the provided command-line (CMD) command.
Example: cmd dir
Example: cmd echo Hello from CMD!

Usage: commitments [check]
Description: Evaluates all commitments and fires triggers.

Commitment YAML fields (examples):

  name: Exercise Twice Weekly
  type: commitment
  frequency: { times: 2, period: week }
  associated_items:
    - { type: habit, name: Exercise }
    - { type: task, name: Morning Run }
  triggers:
    on_met:
      - { type: achievement, name: Exercise streak! }
      - { type: script, path: Scripts/congrats.chs }

  name: Never Smoke
  type: commitment
  never: true
  forbidden_items:
    - { type: habit, name: Smoke }
  triggers:
    on_violation:
      - { type: reward, name: Reflection Needed, properties: { category: Health } }

Usage: complete <item_type> <item_name>
Description: Marks an item as complete for today and updates tracking (streaks, sessions).
Examples:
  complete task "Deep Work" minutes:50
  complete routine "Morning Routine"
  complete appointment "Dentist" attended:true
  complete appointment "Dentist" no_show:true  (records a session but does NOT count as completion)

Usage: copy <item_type> <source_item_name> [new_item_name] [property_key:property_value ...]
Description: Creates a duplicate of an existing item, optionally with a new name and modified properties.
Example: copy note MyMeetingNotes MyMeetingNotes_Copy
Example: copy task "Old Task" "New Task" status:pending priority:high

Usage: count <item_type> [property_key:property_value ...]
Description: Counts items of a specific type, optionally filtered by properties.
Example: count note category:work
Example: count task status:pending priority:high

Usage: create <item_type> <item_name> [property_key:property_value ...]
Description: Creates a new item of the specified type with the given name and properties.
Example: create note MyMeetingNotes category:work priority:high

Note: For 'alarm' and 'reminder' item types, you can add a 'script' property to execute a .chs file when triggered.
Example: create alarm MyAlarm time:08:00 script:Scripts/my_script.chs

Linking alarms/reminders to items:
- Add a 'target' object to the YAML (via properties or by editing the file) to execute an action on trigger.
  target:
    type: task
    name: "Deep Work"
    action: complete   # or: open | set_status
    status: completed  # required only when action == set_status
    properties: { minutes: 25 }  # optional extra args for the action

Usage: cut <item_name>
Description: Removes an item from the current day's schedule.
Example: cut "Morning Routine"

Usage: dashboard
Description: Opens the Chronos dashboard UI in your default browser.
Also pre-bundles User/Settings YAML into generated/settings_bundle.js for the UI to consume.

Usage: delete [-f|--force] <item_type> <item_name> [property_key:property_value ...]
Description: Deletes an item of the specified type. Use -f or --force to skip confirmation.
Example: delete note MyOldNote --force

Usage: dismiss <alarm_name>
Description: Dismisses a specified alarm for the remainder of the current day.
Example: dismiss "Morning Alarm"

Usage: echo <text_to_print>
Description: Prints the provided text to the console.
Example: echo Hello, World!

Usage: edit <item_type> <item_name> [editor:<editor_name>] [property_key:property_value ...]
Description: Opens an item in a text editor for modification.
Example: edit note MyMeetingNotes editor:nvim

Usage:
  export all [filename.zip]
  export <filename> <command> [args...]

Description:
  export all: Zips the entire User/ directory into User/Exports/[filename].zip.
  export filename: Executes a command and saves its table output to YAML in User/Exports/.

Example:
  export all chronos_backup.zip
  export my_tasks.yml list tasks priority:high

Usage: filter <item_type> [property:value ...] | filter all | filter off
Description: Sets or clears the active filter for Chronos items.
Example: filter note category:work
Example: filter all
Example: filter off

Usage: find <item_type> <keyword> [property_key:property_value ...]
Description: Searches for items of the specified type based on a keyword and optional properties.
Example: find note meeting category:work

Usage: get <item_type> <item_name> <property_key> [variable_name:<var_name>] [property_key:property_value ...]
Description: Retrieves the value of a specific property from an item.
Example: get note MyMeetingNotes category variable_name:my_category

Usage: help
Description: Displays this help message, listing all available commands and their usage.

Usage: if <left> <op> <right> then <command> [args...] [else <command> ...]
       if exists <type>[:<name>[:<property>]] then <command> [else <command> ...]
       if exists file:<path> | dir:<path> | env:<NAME> then <command> [else ...]
Operators: =, !=, >, <, >=, <=, eq, ne, gt, lt, ge, le, matches
Logic: and, or, not/! , parentheses ( ... )
Left/Right forms:
  - status:<key>
  - <type>:<name>:<property>
  - literals (after @var expansion)
Examples:
  if status:energy eq high and exists note:"Journal" then echo "rest"
  if task:Morning_Run:duration > 20 then trim "Morning Run" 5 else echo ok
  if note:"IF Note":priority matches ^h.* then echo HIGH
  if exists note:Journal then echo "journal exists"
  if exists file:README.md then echo HAVE_README
  if exists dir:User/Notes then echo NOTES_DIR
  if exists env:PATH then echo HAS_PATH

Usage:
  import <file_path>

Description:
  - If <file_path> ends with .zip, extracts the backup into the User/ directory.
    Use property overwrite:true or mode:overwrite to overwrite existing files.
  - If <file_path> is a YAML list, imports items (skips if already exist).

Example:
  import User/Exports/my_tasks.yml
  import User/Exports/chronos_backup.zip overwrite:true

Usage: list <item_type> [sort_by:<property_key>] [reverse_sort:True/False] [property_key:property_value ...]
       list <item_type> [list_properties...] then <command> [command_args...]

Description:
  Lists items of the specified type, optionally filtered and sorted by a property.
  Can also pipe the listed items to another command for bulk operations.

Examples:
  list note sort_by:priority reverse_sort:True
  list tasks status:pending then set status:in-progress
  list tasks priority:high then delete

Usage: mark <item_name>:<status>
Description: Marks an item in the daily schedule with a new status.
Example: mark "Morning Routine":completed

Usage: mark <item_name>:<status>
Description: Marks an item in the daily schedule with a new status.
Example: mark "Morning Routine":completed

Usage: miss <item_type> <item_name>
Description: Records a missed occurrence (does not count as completion). Helpful for commitments and appointment no-shows.
Examples:
  miss commitment "Daily Promise"
  miss appointment "Dentist"            (equivalent to no_show)
  miss appointment "Dentist" outcome:no_show

Usage: move <source_item_type> <source_item_name> [new_item_name] [type:<target_item_type>] [name:<new_item_name>] [property_key:property_value ...]
Description: Moves an item to a new item type, renames it, or both.
Example: move note MyOldNote MyNewNote
Example: move note MyNote type:task
Example: move note MyNote MyTask type:task

Usage: new <item_type> <item_name> [property_key:property_value ...]
Description: Creates a new item of the specified type with the given name and properties.
Example: new note MyMeetingNotes category:work priority:high

Note: For 'alarm' and 'reminder' item types, you can add a 'script' property to execute a .chs file when triggered.
Example: new alarm MyAlarm time:08:00 script:Scripts/my_script.chs

Usage: pause [message]
Description: Pauses script execution until a key is pressed. Displays an optional message.
Example: pause
Example: pause Script paused. Press Enter to proceed.

Usage:
  points balance
  points add <n> [reason:<text>]
  points subtract <n> [reason:<text>]
  points history [<last_N>]

Usage: powershell <powershell_code>
Description: Executes the provided PowerShell code.
Example: powershell Get-Process | Select-Object -First 3
Example: powershell Write-Host "Hello from PowerShell!"

Usage: profile show
       profile get <nickname|line1|line2|line3>
       profile set [nickname:<value>] [line1:"..."] [line2:"..."] [line3:"..."]
       profile set-line <1|2|3> <text...>

Description:
  Views or updates profile details stored in User/profile.yml. Supports a welcome block with line1/line2/line3.
  Variables like @nickname expand in the welcome lines.

Examples:
  profile show
  profile set nickname:Alice
  profile set line2:"🚀 Welcome, @nickname" line3:"🌌 Navigate your reality"
  profile set-line 2 🚀 Welcome, @nickname

Usage: redeem reward <name>
Description: Redeems a reward, deducting points and delivering its target.
Examples:
  redeem reward "Game Break"

Usage: remove <item_type> <item_name> <property_key>
Description: Removes a specified property from an item.
Example: remove note MyMeetingNotes category

Usage: rename <item_type> <old_name> <new_name> [properties]
Description: Renames an existing item.
Example: rename note MyOldNote MyNewNote

Usage:
  review daily [YYYY-MM-DD]
  review weekly [YYYY-WW]
  review monthly [YYYY-MM]
  review export <daily|weekly|monthly> <period>
  review open <daily|weekly|monthly> <period>

Usage: set <item_type> <item_name> <property_key>:<value> [...]
       set var <variable_name>:<value>
Description: Sets properties of an item or defines a script variable.
Example: set note MyMeetingNotes priority:high category:work
Example: set var my_variable:some_value

Special (goals):
  set goal "<name>" template:true      # mark goal as a template
  set goal "<name>" apply:true         # instantiate milestones from template

Usage: settings <file_shortcut> <property> <value>
Description: Modifies a setting in a specified settings file.
Arguments:
  <file_shortcut>: A shorthand for the settings file name (e.g., 'buffer' for 'Buffer_Settings.yml').
  <property>: The name of the property to modify. Use dot notation for nested properties (e.g., 'global_dynamic_buffer.buffer_interval_minutes').
  <value>: The new value for the property.

Usage: skip <alarm_name>
Description: Skips a specified alarm for the remainder of the current day.
Example: skip "Morning Alarm"

Usage: snooze <alarm_name>
Description: Snoozes a specified alarm for its configured snooze duration.
Example: snooze "Morning Alarm"

Views or sets user status variables.

Usage: status <indicator>:<value>
       status (to view current status)

Examples:
  status emotion:happy
  status energy:low

Usage: theme <subcommand>
Subcommands:
  list                 List available themes
  current              Show current theme/background/text
  set <name>           Set theme by name (from theme_settings.yml)
  set-colors [background:<name|#hex>] [text:<name|#hex>]
                       Set explicit console colors (overrides theme)
Notes:
- Themes come from User/Settings/theme_settings.yml (themes: { name: { background, text } }).
- Current selection is stored in User/profile.yml under 'theme' or 'console: { theme }'.
- Explicit 'background'/'text' in profile override the theme.

Usage:
  timer start <profile> [type:<item_type> name:<item_name>] [cycles:N] [auto_advance:true|false]
  timer pause | resume | stop | status
  timer profiles list | view <name> | save <name> [k:v ...] | delete <name>

Description: No help message available.

Usage: track <item_type> <item_name>
Description: Displays tracking data for a specific item (streaks, sessions, minutes, history).
Examples:
  track task "Deep Work"
  track routine "Morning Routine"

Usage: trim <item_name> <amount_in_minutes>
Description: Reduces the duration of an item in the current day's schedule.
Example: trim "Morning Routine" 10

Usage: unset var <name>
Description: Removes a script variable from the current session.
Example: unset var project

Usage: vars [name:<varname>]
Description: Lists current script variables or a single variable by name.
Example: vars
Example: vars name:project

Usage: view <item_type> <item_name> [property_key:property_value ...]
Description: Displays the content and properties of a specific item.
Example: view note MyMeetingNotes