Support Produced by OmniGraffle 7.5 test 2017-09-15 03:22:04 +0000 phone/email/twitter +1 206-523-4152 or 800-315-OMNI

OmniFocus TaskPaper Reference Guide

This article has not been updated for OmniFocus 4.

OmniFocus includes support for copying items to the pasteboard as TaskPaper text. You can also paste TaskPaper text into the OmniFocus outline.

Copying in the TaskPaper format

In the Mac app, this is done using the Copy as TaskPaper option found in the Edit menu or contextual menu.

On iOS, you just use the regular Copy option found in the contextual menu or Share sheet. You’ll then get TaskPaper text when pasting somewhere that only accepts plain text.

What is TaskPaper text? Quoting from the TaskPaper Users Guide:

TaskPaper’s file format is fairly simple. Here’s how TaskPaper reads a file:

Files are expected to use the UTF-8 encoding and use ‘\n’ to separate lines.

A task is a line that begins with a hyphen followed by a space (‘- ‘) which can optionally be prefixed (i.e indented) with tabs or spaces. A task can have zero or more tags anywhere on the line (not just trailing at the end).

A project is a line that isn’t a task and ends with a colon (‘:’), or a colon (‘:\n’) followed by a newline. Tags can exist after the colon, but if any non-tag text is present, then it won’t be recognized as a project.

A note is any line that doesn’t match the task or project rules.

Indentation level (with tabs, not spaces) defines ownership. For instance, if you indent one task under another task, then it is considered a subtask. Tasks and notes own all objects that are indented underneath them. Empty lines are ignored when calculating ownership.

A tag has the form “@tag”, i.e. it starts with an “at” character (“@”), followed by a run of non-whitespace characters. A tag can optionally have a value assigned to it. The value syntax immediately follows the tag word (no whitespace between) and is enclosed by parentheses: ‘(‘ and ‘)’. The value text inside can have whitespace, but no newlines. Here is an example of a tag with a value: @tag(tag’s value)

OmniFocus imports and exports the various non-note metadata attached to an item as TaskPaper tags. We currently support the following tags (listed alphabetically):

  • @autodone(bool) - whether the item automatically completes itself when its children are complete (true) or not (false). Named to match @done.
  • @context(string) - the context to assign

With OmniFocus 3, @context(string) is replaced by @tags(stringA, stringB, etc.) to support adding multiple OmniFocus tags to an item, e.g. @tags(work, online, quick wins).

  • @defer(date) - defer until date, e.g. 2016-04-19 5pm or next Thursday -3d
  • @done(date) - completed on date
  • @due(date) - due on date
  • @estimate(time span) - time estimate, e.g. 2h for 2 hours or 3w for 3 weeks.
  • @flagged - present when an item is flagged
  • @parallel(bool) - whether children are parallel (true) or sequential (false)
  • @repeat-method(method) - the repeat method: fixed, start-after-completion, or due-after-completion
  • @repeat-rule(rule) - an ICS repeat rule (see RFC244557), e.g. FREQ=WEEKLY;INTERVAL=1

If you’re trying to figure out how to format TaskPaper text to paste into OmniFocus, the best thing to do is create your item in OmniFocus, then copy and paste it into a text editor. You’ll see every tag attached to the item and the correct formatting.

Last Modified: Dec 13, 2023

Can we help?
+1 206-523-4152 or 800-315-OMNI

Was this article helpful?

Still need help?
+1 206-523-4152 or 800-315-OMNI