• Configuration
  • Location
  • Values
    • disable_links
    • last_version_check
    • max_comment_length
    • next_id
    • path
    • natural_language_only
    • no_sections
    • sort_value
    • spinners
    • timeout
    • timezone
    • token
    • timeprovider
    • task_create_command
    • task_comment_command
    • task_complete_command
    • vecprojects
    • verbose

If the config does not exist, Tod will prompt for your initial Todoist API token and create a default config with the following values:

{
  "bell_on_failure": true,
  "bell_on_success": false,
  "completed": null,
  "disable_links": false,
  "last_version_check": null,
  "max_comment_length": null,
  "mock_select": null,
  "mock_string": null,
  "mock_url": null,
  "natural_language_only": null,
  "next_id": null,
  "next_taskv1": null,
  "no_sections": null,
  "path": "See Location - Platform Specific",
  "projectsv1": [],
  "sort_value": {
    "deadline_days": 5,
    "deadline_value": 30,
    "no_due_date": 80,
    "not_recurring": 50,
    "now": 200,
    "overdue": 150,
    "priority_high": 4,
    "priority_low": 1,
    "priority_medium": 3,
    "priority_none": 2,
    "today": 100
  },
  "spinners": true,
  "timeout": null,
  "timezone": "",
  "token": "Your Todoist API Todken",
  "vecprojects": [],
  "verbose": null
}

The Config can be deleted with tod config reset at any time, and it will be re-created upon next execution.

Data is stored in JSON format in $XDG_CONFIG_HOME/tod.cfg. This defaults to:

• ~/.config/tod.cfg on Linux
• ~/Library/Application Support/tod.cfg on Mac
• No idea about Windows, sorry!

  type: boolean
  default: false

Triggers the terminal bell on successful completion of a command

  type: boolean
  default: true

Triggers the terminal bell on an error

  type: boolean
  default: false

If true, disables OSC8 linking and just displays plain text

  type: nullable string
  default: null
  possible_values: any string in format YYYY-MM-DD

Holds a string date, i.e. "2023-08-30" representing the last time crates.io was checked for the latest tod version. Tod will check crates.io a maximum of once per day.

  type: nullable positive integer
  default: null
  possible_values: Any positive integer or null

The maximum number of characters that will be printed in total when showing comments.

If not set, this is dynamically calculated at runtime based on terminal window size (using the term_size crate).

  type: nullable string
  default: null
  possible values: null or any positive integer in string form

When task next is executed the ID is stored in this field. When task complete is run the field is set back to null

  type: string
  default: $XDG_CONFIG_HOME/tod.cfg
  possible values: Any path

Location of the tod configuration file

  type: nullable boolean
  default: null
  possible values: null, true, or false

If true, the datetime selection in project schedule will go straight to natural language input.

  type: nullable boolean
  default: null
  possible values: null, true, or false

If true will not prompt for a section whenever possible

Tasks are ranked by points and the first is returned, the points are the sum of the following:

• Task is overdue: 150
• The date is today with no time: 100
• The date is today with time in next or last 15 min: 200
• No date: 80
• Not recurring: 50
• Task has no priority: 2
• Priority 1: 1
• Priority 2: 3
• Priority 3: 4

The math for how much a deadline contributes in points is a little more involved. It is based on the number of days before the deadline (closer = more) and the value per day.

The formula is max(deadline_days - number of days until deadline, 0) * deadline_value

The default for deadline_days is 5, and deadline_value is 30. For example:

• 6 days before the deadline it is 0
• 4 days before deadline the value is 30
• on the day of the deadline it is 150
• 2 days after the deadline it is 210

Defaults:

  {
    "deadline_days": 5,
    "deadline_value": 30,
    "no_due_date": 80,
    "not_recurring": 50,
    "now": 200,
    "overdue": 150,
    "priority_high": 4,
    "priority_low": 1,
    "priority_medium": 3,
    "priority_none": 2,
    "today": 100
  },

These values are u8, so they can be 0-255 (must not exceed 255) - if they exceed 255, Tod will report a config parse error.

For examples, see sort_value_examples

  type: nullable boolean
  default: null
  possible values: null, true, or false

Controls whether the spinner is displayed when an API call occurs. Useful for cases where the terminal output is captured. null is considered the same as true.

You can also use the environment variable DISABLE_SPINNER to turn them off.

  DISABLE_SPINNER=1 tod task create

  type: integer
  default: 30 (seconds)
  possible values: Any positive number in seconds

  type: string
  default: No default
  possible values: Any timezone string i.e. "Canada/Pacific"

You will be prompted for timezone on first run

  type: string
  default: No default
  possible values: Any valid token

You will be prompted for your Todoist API token on first run or if this is otherwise invalid/unset.

  type: string
  default: No default
  possible values: Enum of SystemTimeProvider or FixedTimeProvider

Used for dev/testing only to return fixed time (fixture) for use in test cases. Otherwise defaults to SystemTimeProvider in all other cases.

  type: Nullable array of objects
  default: null
  possible values: List of project objects from the Todoist API

Projects are stored locally in config to help save on API requests and speed up actions taken. Manage this with the project subcommands. The strange naming is because projects was used in previous versions of tod.

type: String
default: None
possible values: A string that is executed within the shell (such as 'echo task commented')

Defaults to None. The Shell command that spanwed for background execution upon a task being commented. Only executes if set. Allows for custom integration with other scripts, code, sounds, or webhooks. Note that only errors (Stderr) are output to the CLI; successful responses (stdout) are supressed.

type: String
default: None
possible values: A string that is executed within the shell (such as 'echo task created')

Defaults to None. The Shell command that spanwed for background execution upon a task being added/created. Only executes if set, for both regular and quick-add task creation. Allows for custom integration with other scripts, code, sounds, or webhooks. Note that only errors (Stderr) are output to the CLI; successful responses (stdout) are supressed.

type: String
default: None
possible values: A string that is executed within the shell (such as 'echo task completed')

Defaults to None. The Shell command that spanwed for background execution upon a task being completed. Only executes if set. Allows for custom integration with other scripts, code, sounds, or webhooks. Note that only errors (Stderr) are output to the CLI; successful responses (stdout) are supressed.

type: Regex
default: None
possible values: A Regex expression

Defaults to None. This field must be a valid JSON-escaped regex value. Any tasks for which their title matches this Regex will NOT be returned.

For example, this might be used to exclude uncompletable tasks.

type: Regex
default: None
possible values: A Regex expression

Defaults to None. This field must be a valid JSON-escaped regex value. Any comments for which their title matches this Regex will NOT be returned.

  type: nullable boolean
  default: null
  possible values: null, true, or false

Outputs additional information in console to assist with debugging.

The following example will sort based on priority, then due date (including a deadline/due date 14 days in advance).

  "sort_value": {
    "deadline_days": 14,
    "deadline_value": 3,
    "no_due_date": 10,
    "not_recurring": 0,
    "now": 50,
    "overdue": 54,
    "priority_high": 200,
    "priority_low": 100,
    "priority_medium": 150,
    "priority_none": 50,
    "today": 42
  },

This example sorts based on NOW, then Due, then Priority (with priority only used for tie-breaking)

{
  "deadline_days": 14,
  "deadline_value": 3,

  "no_due_date": 5,
  "not_recurring": 0,
  "now": 255,
  "overdue": 200,
  "today": 150,
  "priority_high": 4,
  "priority_medium": 3,
  "priority_low": 2,
  "priority_none": 1
}

This example sorts based on Due Date only, then prrority

{
  "deadline_days": 14,
  "deadline_value": 10,
  "no_due_date": 0,
  "not_recurring": 0,
  "now": 50,
  "overdue": 150,
  "today": 100,
  "priority_high": 4,
  "priority_medium": 3,
  "priority_low": 2,
  "priority_none": 1
}

This example purely uses due date (ignores priority)

  "deadline_days": 14,
  "deadline_value": 18,
  "no_due_date": 0,
  "not_recurring": 0,
  "now": 50,
  "overdue": 255,
  "today": 180,
  "priority_high": 0,
  "priority_medium": 0,
  "priority_low": 0,
  "priority_none": 0
}