na

A command line tool for adding and listing per-project todos.

If you’re one of the rare people like me who find this useful, feel free to buy me some coffee.

The current version of na is 1.2.63.

na (“next action”) is a command line tool designed to make it easy to see what your next actions are for any project, right from the command line. It works with TaskPaper-formatted files (but any plain text format will do), looking for @na tags (or whatever you specify) in todo files in your current folder.

Used with Taskpaper files, it can add new action items quickly from the command line, automatically tagging them as next actions. It can also mark actions as completed, delete them, archive them, and move them between projects.

It can also auto-display next actions when you enter a project directory, automatically locating any todo files and listing their next actions when you cd to the project (optionally recursive). See the Prompt Hooks section for details.

Installation

Assuming you have Ruby and RubyGems installed, you can just run gem install na. If you run into errors, try gem install --user-install na, or use sudo gem install na.

If you’re using Homebrew, you have the option to install via brew-gem:

brew install brew-gem
brew gem install na

If you don’t have Ruby/RubyGems, you can install them pretty easily with Homebrew, rvm, or asdf. I can’t swear this tool is worth the time, but there are a lot of great gems available…

You can find the na source code (MIT license) on GitHub.

Optional Dependencies

If you have gum installed, na will use it for command line input when adding tasks and notes. If you have fzf installed, it will be used for menus, falling back to gum if available.

Features

You can list next actions in files in the current directory by typing na. By default, na looks for *.taskpaper files and extracts items tagged @na and not @done. This can be modified to work with a single global file, and all of these options can be changed in the configuration.

Easy matching

na features intelligent project matching. Every time it locates a todo file, it adds the project to the database. Once a project is recorded, you can list its actions by using any portion of the parent directories or file names. If your project is in ~/Sites/dev/markedapp, you could quickly list its next actions by typing na next dev/mark. Creat paths by separating with / or :, separate multiple queries with spaces. na will always look for the shortest match for a path.

Recursion

na can also recurse subdirectories to find all todo files in child folders as well. Use the -d X to search X levels deep from the current directory. na -r with no arguments will recurse from your current location, looking for todo files 3 directories deep.

Adding todos

You can also quickly add todo items from the command line with the add subcommand. The script will look for a file in the current directory with a .taskpaper extension (configurable).

If found, it will try to locate an Inbox: project, or create one if it doesn’t exist. Any arguments after add will be combined to create a new task in TaskPaper format. They will automatically be assigned as next actions (tagged @na) and will show up when na lists the tasks for the project.

Updating todos

You can mark todos as complete, delete them, add and remove tags, change priority, and even move them between projects with the na update command.

Terminology

Todo: Refers to a todo file, usually a TaskPaper document

Project: Refers to a project within the TaskPaper document, specified by an alphanumeric name (spaces allowed) followed by a colon. Projects can be nested by indenting a tab beyond the parent projects indentation.

Action: Refers to an individual task, specified by a line starting with a hyphen (-)

Note: Refers to lines appearing between action lines that start without hyphens. The note is attached to the preceding action regardless of indentation.

Usage

NAME
    na - Add and list next actions for the current project

SYNOPSIS
    na [global options] command [command options] [arguments...]

VERSION
    1.2.63

GLOBAL OPTIONS
    -a, --add               - Add a next action (deprecated, for backwards compatibility)
    --add_at=POSITION       - Add all new/moved entries at [s]tart or [e]nd of target project (default: start)
    --[no-]color            - Colorize output (default: enabled)
    --cwd_as=TYPE           - Use current working directory as [p]roject, [t]ag, or [n]one (default: none)
    -d, --depth=DEPTH       - Recurse to depth (default: 3)
    --[no-]debug            - Display verbose output
    --ext=EXT               - File extension to consider a todo file (default: taskpaper)
    -f, --file=PATH         - Use a single file as global todo, use initconfig to make permanent (default: none)
    --help                  - Show this message
    --include_ext           - Include file extension in display
    -n, --note              - Prompt for additional notes (deprecated, for backwards compatibility)
    -p, --priority=PRIORITY - Set a priority 0-5 (deprecated, for backwards compatibility) (default: none)
    --[no-]pager            - Enable pagination (default: enabled)
    -r, --[no-]recurse      - Recurse 3 directories deep (deprecated, for backwards compatability)
    -t, --na_tag=TAG        - Tag to consider a next action (default: na)
    --template=PATH         - Provide a template for new/blank todo files, use initconfig to make permanent (default: none)
    --version               - Display the program version

COMMANDS
    add                 - Add a new next action
    archive             - Mark an action as @done and archive
    changes, changelog  - Display the changelog
    complete, finish    - Find and mark an action as @done
    completed, finished - Display completed actions
    edit                - Edit an existing action
    find, grep, search  - Find actions matching a search pattern
    help                - Shows a list of commands or help for one command
    init, create        - Create a new todo file in the current directory
    initconfig          - Initialize the config file using current global options
    next, show          - Show next actions
    open                - Open a todo file in the default editor
    projects            - Show list of projects for a file
    prompt              - Show or install prompt hooks for the current shell
    restore, unfinish   - Find and remove @done tag from an action
    saved               - Execute a saved search
    tag                 - Add tags to matching action(s)
    tagged              - Find actions matching a tag
    todos               - Show list of known todo files
    undo                - Undo the last change
    update              - Update an existing action

Commands

add

Example: na add This feature @idea I have

If you run the add command with no arguments, you’ll be asked for input on the command line.

Adding notes

Use the --note switch to add a note. If STDIN (piped) input is present when this switch is used, it will be included in the note. A prompt will be displayed for adding additional notes, which will be appended to any STDIN note passed. Press CTRL-d to end editing and save the note.

Notes are not displayed by the next/tagged/find commands unless --notes is specified.

NAME
    add - Add a new next action

SYNOPSIS

    na [global options] add [command options] ACTION

DESCRIPTION
    Provides an easy way to store todos while you work. Add quick   reminders and (if you set up Prompt Hooks) they'll automatically display   next time you enter the directory.   If multiple todo files are found in the current directory, a menu will   allow you to pick to which file the action gets added. 

COMMAND OPTIONS
    --at=POSITION                   - Add task at [s]tart or [e]nd of target project (default: none)
    -d, --depth=DEPTH               - Search for files X directories deep (default: 1)
    -f, --file=PATH                 - Specify the file to which the task should be added (default: none)
    --finish, --done                - Mark task as @done with date
    --in, --todo=TODO_FILE          - Add to a known todo file, partial matches allowed (default: none)
    -n, --note                      - Prompt for additional notes. STDIN input (piped) will be treated as a note if present.
    -p, --priority=PRIO             - Add a priority level 1-5 (default: 0)
    -t, --tag=TAG                   - Use a tag other than the default next action tag (default: none)
    --to, --project, --proj=PROJECT - Add action to specific project (default: Inbox)
    -x                              - Don't add next action tag to new entry

EXAMPLES

    # Add a new action to the Inbox, including a tag
    na add "A cool feature I thought of @idea"

    # Add a new action to the Inbox, set its @priority to 4, and prompt for an additional note.
    na add "A bug I need to fix" -p 4 -n

    # A parenthetical at the end of an action is interpreted as a note
    na add "An action item (with a note)"
edit
NAME
    edit - Edit an existing action

SYNOPSIS

    na [global options] edit [command options] ACTION

DESCRIPTION
    Open a matching action in your default $EDITOR.   If multiple todo files are found in the current directory, a menu will   allow you to pick which file to act on.   Natural language dates are expanded in known date-based tags. 

COMMAND OPTIONS
    -d, --depth=DEPTH      - Search for files X directories deep (default: 1)
    --[no-]done            - Include @done actions
    -e, --regex            - Interpret search pattern as regular expression
    --file=PATH            - Specify the file to search for the task (default: none)
    --in, --todo=TODO_FILE - Use a known todo file, partial matches allowed (default: none)
    --[no-]search_notes    - Include notes in search (default: enabled)
    --tagged=TAG           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
    -x, --exact            - Match pattern exactly

EXAMPLE

    # Find "An existing task" action and open it for editing
    na edit "An existing task"
find

Example: na find cool feature idea

Unless --exact is specified, search is tokenized and combined with AND, so na find cool feature idea translates to cool AND feature AND idea, matching any string that contains all of the words. To make a token required and others optional, add a + before it (e.g. cool +feature idea is (cool OR idea) AND feature). Wildcards allowed (* and ?), use --regex to interpret the search as a regular expression. Use -v to invert the results (display non-matching actions only).

NAME
    find - Find actions matching a search pattern

SYNOPSIS

    na [global options] find [command options] PATTERN

DESCRIPTION
    Search tokens are separated by spaces. Actions matching all tokens in the pattern will be shown   (partial matches allowed). Add a + before a token to make it required, e.g. `na find +feature +maybe`,   add a - or ! to ignore matches containing that token. 

COMMAND OPTIONS
    -d, --depth=DEPTH                      - Recurse to depth (default: none)
    --[no-]done                            - Include @done actions
    -e, --regex                            - Interpret search pattern as regular expression
    --in=TODO_PATH                         - Show actions from a specific todo file in history. May use wildcards (* and ?) (default: none)
    --nest                                 - Output actions nested by file
    --[no-]notes                           - Include notes in output
    -o, --or                               - Combine search tokens with OR, displaying actions matching ANY of the terms
    --omnifocus                            - Output actions nested by file and project
    --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
    --save=TITLE                           - Save this search for future use (default: none)
    --[no-]search_notes                    - Include notes in search (default: enabled)
    --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
    -v, --invert                           - Show actions not matching search pattern
    -x, --exact                            - Match pattern exactly

EXAMPLES

    # Find all actions containing feature, idea, and swift
    na find feature idea swift

    # Find all actions containing feature and idea but NOT swift
    na find feature idea -swift

    # Find all actions containing the exact text "feature idea"
    na find -x feature idea
init, create
NAME
    init - Create a new todo file in the current directory

SYNOPSIS

    na [global options] init [PROJECT]

EXAMPLES

    # Generate a new todo file, prompting for project name
    na init

    # Generate a new todo for a project called warpspeed
    na init warpspeed
next, show

Examples:

  • na next (list all next actions in the current directory)
  • na next -d 3 (list all next actions in the current directory and look for additional files 3 levels deep from there)
  • na next marked2 (show next actions from another directory you’ve previously used na on)

To see all next actions across all known todos, use na next "*". You can combine multiple arguments to see actions across multiple todos, e.g. na next marked nvultra.

NAME
    next - Show next actions

SYNOPSIS

    na [global options] next [command options] [QUERY]

DESCRIPTION
    Next actions are actions which contain the next action tag (default @na),   do not contain @done, and are not in the Archive project.   Arguments will target a todo file from history, whether it's in the current   directory or not. Todo file queries can include path components separated by /   or :, and may use wildcards (`*` to match any text, `?` to match a single character). Multiple queries allowed (separate arguments or separated by comma). 

COMMAND OPTIONS
    --all                                  - Show next actions from all known todo files (in any directory)
    -d, --depth=DEPTH                      - Recurse to depth (default: none)
    --[no-]done                            - Include @done actions
    --exact                                - Search query is exact text match (not tokens)
    --file=TODO_FILE                       - Display matches from specific todo file ([relative] path) (default: none)
    --in, --todo=TODO                      - Display matches from a known todo file anywhere in history (short name) (may be used more than once, default: none)
    --nest                                 - Output actions nested by file
    --[no-]notes                           - Include notes in output
    --omnifocus                            - Output actions nested by file and project
    -p, --prio, --priority=PRIORITY        - Match actions with priority, allows <>= comparison (may be used more than once, default: none)
    --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
    --regex                                - Search query is regular expression
    --save=TITLE                           - Save this search for future use (default: none)
    --search, --find, --grep=QUERY         - Filter results using search terms (may be used more than once, default: none)
    --[no-]search_notes                    - Include notes in search (default: enabled)
    -t, --tag=TAG                          - Alternate tag to search for (default: none)
    --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)

EXAMPLES

    # display the next actions from any todo files in the current directory
    na next

    # display the next actions from the current directory, traversing 3 levels deep
    na next -d 3

    # display next actions for a project you visited in the past
    na next marked
projects

List all projects in a file. If arguments are provided, they’re used to match a todo file from history, otherwise the todo file(s) in the current directory will be used.

NAME
    projects - Show list of projects for a file

SYNOPSIS

    na [global options] projects [command options] [QUERY]

DESCRIPTION
    Arguments will be interpreted as a query for a known todo file,   fuzzy matched. Separate directories with /, :, or a space, e.g. `na projects code/marked` 

COMMAND OPTIONS
    -d, --depth=DEPTH - Search for files X directories deep (default: 1)
    -p, --paths       - Output projects as paths instead of hierarchy
saved

The saved command runs saved searches. To save a search, add --save SEARCH_NAME to a find or tagged command. The arguments provided on the command line will be saved to a search file (/.local/share/na/saved_searches.yml), with the search named with the SEARCH_NAME parameter. You can then run the search again with na saved SEARCH_NAME. Repeating the SEARCH_NAME with a new find/tagged command will overwrite the previous definition.

Search names can be partially matched when calling them, so if you have a search named “overdue,” you can match it with na saved over (shortest match will be used).

Run na saved without an argument to list your saved searches.

As a shortcut, if na is run with one argument that matches the name of a saved search, it will execute that search, so running na maybe is the same as running na saved maybe.

NAME
    saved - Execute a saved search

SYNOPSIS

    na [global options] saved [command options] [SEARCH_TITLE]...

DESCRIPTION
    Run without argument to list saved searches 

COMMAND OPTIONS
    -d, --delete - Delete the specified search definition
    -e, --edit   - Open the saved search file in $EDITOR
    -s, --select - Interactively select a saved search to run

EXAMPLES

    # save a search called "maybelater"
    na tagged "+maybe,+priority<=3" --save maybelater

    # perform the search named "maybelater"
    na saved maybelater

    # perform the search named "maybelater", assuming no other searches match "maybe"
    na saved maybe

    # na run with no command and a single argument automatically performs a matching saved search
    na maybe

    # list available searches
    na saved
tagged

Example: na tagged feature +maybe.

Separate multiple tags/value comparisons with commas. By default tags are combined with AND, so actions matching all of the tags listed will be displayed. Use + to make a tag required and ! to negate a tag (only display if the action does not contain the tag). When + and/or ! are used, undecorated tokens become optional matches. Use -v to invert the search and display all actions that don’t match.

You can also perform value comparisons on tags. A value in a TaskPaper tag is added by including it in parenthesis after the tag, e.g. @due(2022-10-10 05:00). You can perform numeric comparisons with <, >, <=, >=, ==, and !=. If comparing to a date, you can use natural language, e.g. na tagged "due<today".

To perform a string comparison, you can use *= (contains), ^= (starts with), $= (ends with), or = (matches). E.g. na tagged "note*=video".

NAME
    next - Show next actions

SYNOPSIS

    na [global options] next [command options] [QUERY]

DESCRIPTION
    Next actions are actions which contain the next action tag (default @na),   do not contain @done, and are not in the Archive project.   Arguments will target a todo file from history, whether it's in the current   directory or not. Todo file queries can include path components separated by /   or :, and may use wildcards (`*` to match any text, `?` to match a single character). Multiple queries allowed (separate arguments or separated by comma). 

COMMAND OPTIONS
    --all                                  - Show next actions from all known todo files (in any directory)
    -d, --depth=DEPTH                      - Recurse to depth (default: none)
    --[no-]done                            - Include @done actions
    --exact                                - Search query is exact text match (not tokens)
    --file=TODO_FILE                       - Display matches from specific todo file ([relative] path) (default: none)
    --in, --todo=TODO                      - Display matches from a known todo file anywhere in history (short name) (may be used more than once, default: none)
    --nest                                 - Output actions nested by file
    --[no-]notes                           - Include notes in output
    --omnifocus                            - Output actions nested by file and project
    -p, --prio, --priority=PRIORITY        - Match actions with priority, allows <>= comparison (may be used more than once, default: none)
    --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
    --regex                                - Search query is regular expression
    --save=TITLE                           - Save this search for future use (default: none)
    --search, --find, --grep=QUERY         - Filter results using search terms (may be used more than once, default: none)
    --[no-]search_notes                    - Include notes in search (default: enabled)
    -t, --tag=TAG                          - Alternate tag to search for (default: none)
    --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)

EXAMPLES

    # display the next actions from any todo files in the current directory
    na next

    # display the next actions from the current directory, traversing 3 levels deep
    na next -d 3

    # display next actions for a project you visited in the past
    na next marked
todos

List all known todo files from history.

NAME
    todos - Show list of known todo files

SYNOPSIS

    na [global options] todos [command options] [QUERY]

DESCRIPTION
    Arguments will be interpreted as a query against which the   list of todos will be fuzzy matched. Separate directories with   /, :, or a space, e.g. `na todos code/marked` 

COMMAND OPTIONS
    -e, --[no-]edit - Open the todo database in an editor for manual modification
update

Example: na update --in na --archive my cool action

The above will locate a todo file matching “na” in todo history, find any action matching “my cool action”, add a dated @done tag and move it to the Archive project, creating it if needed. If multiple actions are matched, a menu is presented (multi-select if fzf is available).

This command will perform actions (tag, untag, complete, archive, add note, etc.) on existing actions by matching your search text. Arguments will be interpreted as search tokens similar to na find. You can use --exact and --regex, as well as wildcards in the search string. You can also use --tagged TAG_QUERY in addition to or instead of a search query.

You can specify a particular todo file using --file PATH or any todo from history using --in QUERY.

If more than one file is matched, a menu will be presented, multiple selections allowed. If multiple actions match the search within the selected file(s), a menu will be presented. If you have fzf installed, you can select one action to update with return, or use tab to mark multiple tasks to which the action will be applied. With gum you can use j, k, and x to mark multiple actions. Use the --all switch to force operation on all matched tasks, skipping the menu.

Any time an update action is carried out, a backup of the file before modification will be made in the same directory with a . prepended and .bak appended (e.g. marked.taskpaper is copied to .marked.taskpaper.bak). Only one undo step is available, but if something goes wrong (and this feature is still experimental, so be wary), you can just copy the “.bak” file back to the original.

Marking a task as complete

You can mark an action complete using --finish, which will add a dated @done tag to the action. You can also mark it @done and immediately move it to the Archive project using --archive.

If you just want the action to stop appearing as a “next action,” you can remove the next action tag using --remove na (or whatever your next action tag is configured as).

If you want to permanently delete an action, use --delete to remove it entirely.

Moving between projects

You can specify a new project for an action (moving it) with --proj PROJECT_PATH. A project path is hierarchical, with each level separated by a colon or slash. If the project path provided roughly matches an existing project, e.g. “mark:bug” would match “Marked:Bugs”, then that project will be used. If no match is found, na will offer to generate a new project/hierarchy for the path provided. Strings will be exact but the first letter will be uppercased.

Adding notes

Use the --note switch to add a note. If STDIN (piped) input is present when this switch is used, it will be included in the note. A prompt will be displayed for adding additional notes, which will be appended to any STDIN note passed. Press CTRL-d to end editing and save the note.

Notes are not displayed by the next/tagged/find commands unless --notes is specified.

See the help output for a list of all available actions.

NAME
    update - Update an existing action

SYNOPSIS

    na [global options] update [command options] ACTION

DESCRIPTION
    Provides an easy way to complete, prioritize, and tag existing actions.   If multiple todo files are found in the current directory, a menu will   allow you to pick which file to act on. 

COMMAND OPTIONS
    -a, --archive                          - Add a @done tag to action and move to Archive
    --all                                  - Act on all matches immediately (no menu)
    --at=POSITION                          - When moving task, add at [s]tart or [e]nd of target project (default: none)
    -d, --depth=DEPTH                      - Search for files X directories deep (default: 1)
    --delete                               - Delete an action
    --[no-]done                            - Include @done actions
    -e, --regex                            - Interpret search pattern as regular expression
    --edit                                 - Open action in editor (vim).             Natural language dates will be parsed and converted in date-based tags.
    -f, --finish                           - Add a @done tag to action
    --file=PATH                            - Specify the file to search for the task (default: none)
    --in, --todo=TODO_FILE                 - Use a known todo file, partial matches allowed (default: none)
    -n, --note                             - Prompt for additional notes. Input will be appended to any existing note.     If STDIN input (piped) is detected, it will be used as a note.
    -o, --overwrite                        - Overwrite note instead of appending
    -p, --priority=PRIO                    - Add/change a priority level 1-5 (default: 0)
    --proj, --project=PROJECT[/SUBPROJECT] - Affect actions from a specific project (default: none)
    -r, --remove=TAG                       - Remove a tag from the action, use multiple times or combine multiple tags with a comma,             wildcards (* and ?) allowed (may be used more than once, default: none)
    --replace=TEXT                         - Use with --find to find and replace with new text. Enables --exact when used (default: none)
    --restore                              - Remove @done tag from action
    --search, --find, --grep=QUERY         - Filter results using search terms (may be used more than once, default: none)
    --[no-]search_notes                    - Include notes in search (default: enabled)
    -t, --tag=TAG                          - Add a tag to the action, @tag(values) allowed, use multiple times or combine multiple tags with a comma (may be used more than once, default: none)
    --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
    --to, --move=PROJECT                   - Move action to specific project (default: none)
    -x, --exact                            - Match pattern exactly

EXAMPLES

    # Find "An existing task" action and remove the @na tag from it
    na update --remove na "An existing task"

    # Find "A bug..." action, add @waiting, add/update @priority(4), and prompt for an additional note
    na update --tag waiting "A bug I need to fix" -p 4 -n

    # Add @done to "My cool action" and immediately move to Archive
    na update --archive My cool action
changelog

View recent changes with na changelog or na changes.

NAME
    changes - Display the changelog

SYNOPSIS

    na [global options] changes
complete

Mark an action as complete, shortcut for na update --finish.

NAME
    complete - Find and mark an action as @done

SYNOPSIS

    na [global options] complete [command options] ACTION

COMMAND OPTIONS
    -a, --archive                          - Add a @done tag to action and move to Archive
    --all                                  - Act on all matches immediately (no menu)
    -d, --depth=DEPTH                      - Search for files X directories deep (default: 1)
    -e, --regex                            - Interpret search pattern as regular expression
    --file=PATH                            - Specify the file to search for the task (default: none)
    --in, --todo=TODO_FILE                 - Use a known todo file, partial matches allowed (default: none)
    -n, --note                             - Prompt for additional notes. Input will be appended to any existing note.     If STDIN input (piped) is detected, it will be used as a note.
    -o, --overwrite                        - Overwrite note instead of appending
    --proj, --project=PROJECT[/SUBPROJECT] - Affect actions from a specific project (default: none)
    --search, --find, --grep=QUERY         - Filter results using search terms (may be used more than once, default: none)
    --[no-]search_notes                    - Include notes in search (default: enabled)
    --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
    --to, --move=PROJECT                   - Add a @done tag and move action to specific project (default: none)
    -x, --exact                            - Match pattern exactly

EXAMPLES

    # Find "An existing task" and mark @done
    na complete "An existing task"

    # Alias for complete
    na finish "An existing task"
archive

Mark an action as complete and move to archive, shortcut for na update --archive.

NAME
    archive - Mark an action as @done and archive

SYNOPSIS

    na [global options] archive [command options] ACTION

COMMAND OPTIONS
    --all                                  - Act on all matches immediately (no menu)
    -d, --depth=DEPTH                      - Search for files X directories deep (default: 1)
    --done                                 - Archive all done tasks
    -e, --regex                            - Interpret search pattern as regular expression
    --file=PATH                            - Specify the file to search for the task (default: none)
    --in, --todo=TODO_FILE                 - Use a known todo file, partial matches allowed (default: none)
    -n, --note                             - Prompt for additional notes. Input will be appended to any existing note.     If STDIN input (piped) is detected, it will be used as a note.
    -o, --overwrite                        - Overwrite note instead of appending
    --proj, --project=PROJECT[/SUBPROJECT] - Affect actions from a specific project (default: none)
    --search, --find, --grep=QUERY         - Filter results using search terms (may be used more than once, default: none)
    --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
    -x, --exact                            - Match pattern exactly

EXAMPLE

    # Find "An existing task", mark @done if needed, and move to archive
    na archive "An existing task"
tag

Add, remove, or modify tags.

Use na tag TAGNAME --[search|tagged] SEARCH_STRING to add a tag to matching action (use --all to apply to all matching actions). If you use !TAGNAME it will remove that tag (regardless of value). To change the value of an existing tag (or add it if it doesn’t exist), use ~TAGNAME(NEW VALUE).

NAME
    tag - Add tags to matching action(s)

SYNOPSIS

    na [global options] tag [command options] TAG

DESCRIPTION
    Provides an easy way to tag existing actions.   Use !tag to remove a tag, use ~tag(new value) to change a tag or add a value.   If multiple todo files are found in the current directory, a menu will   allow you to pick which file to act on, or use --all to apply to all matches. 

COMMAND OPTIONS
    --all                          - Act on all matches immediately (no menu)
    -d, --depth=DEPTH              - Search for files X directories deep (default: 1)
    --[no-]done                    - Include @done actions
    -e, --regex                    - Interpret search pattern as regular expression
    --file=PATH                    - Specify the file to search for the task (default: none)
    --in, --todo=TODO_FILE         - Use a known todo file, partial matches allowed (default: none)
    --search, --find, --grep=QUERY - Filter results using search terms (may be used more than once, default: none)
    --[no-]search_notes            - Include notes in search (default: enabled)
    --tagged=TAG                   - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
    -x, --exact                    - Match pattern exactly

EXAMPLES

    # Find "An existing task" action and add @project(warpspeed) to it
    na tag "project(warpspeed)" --search "An existing task"

    # Find all actions tagged @project2 and remove @project1 from them
    na tag "!project1" --tagged project2 --all

    # Remove @project2 from all actions
    na tag "!project2" --all

    # Find "An existing task" and change (or add) its @project tag value to "dirt nap"
    na tag "~project(dirt nap)" --search "An existing task"
undo

Undoes the last file change resulting from an add or update command. If no argument is given, it undoes whatever the last change in history was. If an argument is provided, it’s used to match against the change history, finding a specific file to restore from backup.

Only the most recent change can be undone.

NAME
    undo - Undo the last change

SYNOPSIS

    na [global options] undo [command options] [FILE]...

DESCRIPTION
    Run without argument to undo most recent change 

COMMAND OPTIONS
    -s, --[no-]select, --[no-]choose - Select from available undo files

EXAMPLES

    # Undo the last change
    na undo

    # Undo the last change to a file matching "myproject"
    na undo myproject

Configuration

Global options such as todo extension and default next action tag can be stored permanently by using the na initconfig command. Run na with the global options you’d like to set, and add initconfig at the end of the command. A file will be written to ~/.na.rc. You can edit this manually, or just update it using the initconfig --force command to overwrite it with new settings.

You can see all available global options by running na help.

Example: na --ext md --na_tag next initconfig --force

When this command is run, it doesn’t include options for subcommands, but inserts placeholders for them. If you want to permanently set an option for a subcommand, you’ll need to edit ~/.na.rc. For example, if you wanted the next command to always recurse 2 levels deep, you could edit it to look like this:

---
:ext: taskpaper
:na_tag: na
:d: 1
commands:
  :next:
    :depth: 2
  :add: {}
  :find: {}
  :tagged: {}

Note that I created a new YAML dictionary inside of the :next: command, and added a :depth: key that matches the setting I want to make permanent.

WARNING Don’t touch most of the settings at the top of the auto-generated file. Setting any of them to true will alter the way na interprets the commands you’re running. Most of those options are there for backwards compatibility with the bash version of this tool and will eventually be removed.

Working with a single global file

na is designed to work with one or more TaskPaper files in each project directory, but if you prefer to use a single global TaskPaper file, you can add --file PATH as a global option and specify a single file. This will bypass the detection of any files in the current directory. Make it permanent by including the --file flag when running initconfig.

When using a global file, you can additionally include --cwd_as TYPE to determine whether the current working directory is used as a tag or a project (default is neither). If you add --cwd_as tag to the global options (before the command), the last element of the current working directory will be appended as an @tag (e.g. if you’re in ~/Code/project/doing, the action would be tagged @doing). If you use --cwd_as project the action will be put into a project with the same name as the current directory (e.g. Doing: from the previous example).

Add tasks at the end of a project

By default, tasks are added at the top of the target project (Inbox, etc.). If you prefer new tasks to go at the end of the project by default, include --add_at end as a global option when running initconfig.

Prompt Hooks

You can add a prompt command to your shell to have na automatically list your next actions when you cd into a directory. To install a prompt command for your current shell, just run na prompt install. It works with Zsh, Bash, and Fish. If you’d rather make the changes to your startup file yourself, run na prompt show to get the hook and instructions printed out for copying.

If you’re using a single global file, you’ll need --cwd_as to be tag or project for a prompt command to work. na will detect which system you’re using and provide a prompt command that lists actions based on the current directory using either project or tag.

You can also get output for shells other than the one you’re currently using by adding “bash”, “zsh”, or “fish” to the show or install command.

You can add -r to any of the calls to na to automatically recurse 3 directories deep, or just set the depth config permanently

After installing a hook, you’ll need to close your terminal and start a new session to initialize the new commands.

Changelog

Click to expand

1.2.63

2023-12-14 13:56

FIXED

  • Frozen string issue in completed
  • Remove debug statement

1.2.62

2023-10-05 08:39

FIXED

  • Return empty if na projects QUERY has no results

1.2.61

2023-10-03 12:44

NEW

  • --priority (-p) flag for na next, allows you to only display actions matching a certain @priority value. Can be used multiple times, or combine multiple values with a comma. Allows <> comparisons, and if more than one value is provided, automatically does an OR search

1.2.60

2023-10-03 12:31

NEW

  • Added --search_notes to allow searching of notes when using find or tagged --search. Defaults to true, can be disabled with --no-search_notes

IMPROVED

  • Added --search_notes to completed, restore, edit, and update
  • Add --search_notes to tag
  • Add --search_notes to complete
  • Add --search_notes to next

1.2.59

2023-10-03 07:43

IMPROVED

  • Ignore all YAML headers, even with empty values (which can be mistaked for a project)

FIXED

  • Inserting new project after first project or inside of existing project

1.2.58

2023-09-12 14:11

NEW

  • na next --all to display next actions from all known todo files (any directory)

IMPROVED

  • Middle truncate directory names longer than 1/3 of the screen width

1.2.57

2023-09-11 16:43

FIXED

  • Error when no todo files are located

1.2.56

2023-09-11 11:33

FIXED

  • Write missing backup database if it doesn’t exist

1.2.55

2023-09-11 11:23

IMPROVED

  • Change minimum width for text wrapping to 80 columns

1.2.54

2023-09-11 10:11

IMPROVED

  • Allow selection of action if no search text is provided for tag command
  • If the terminal is less than 60 columns wide, don’t indent or wrap (for display on mobile devices)

1.2.53

2023-09-10 08:26

FIXED

  • Nil error when requesting input

1.2.52

2023-09-10 06:32

FIXED

  • Remove debug statement

1.2.51

2023-09-09 13:20

FIXED

  • Ensure new actions are added within newly created projects
  • When creating a subproject, ensure new project gets inserted

1.2.50

2023-09-09 08:04

NEW

  • Global option --include_ext can be configured to use full

FIXED

  • --no-color wasn’t stripping templated hex codes

1.2.49

2023-09-08 13:34

FIXED

  • New project not being added when requested

1.2.48

2023-09-08 10:19

FIXED

  • Error when na add --to PROJECT was a project that didn’t exist

1.2.47

2023-09-07 10:47

NEW

  • na update --search OLD_TEXT --replace NEW_TEXT (added –replace)

IMPROVED

  • When not showing notes, add an asterisk in the template note
  • When showing notes, indent to the beginning of the action

1.2.46

2023-09-06 21:25

IMPROVED

  • Add --project to archive and update
  • Add --project flag to complete

FIXED

  • Error when creating new project in todo file

1.2.45

2023-09-06 19:19

IMPROVED

  • Change default :dirname coloring to fix an occasional highlighting issue

1.2.44

2023-09-06 11:19

FIXED

  • Error when last_modified.txt hasn’t been written yet

1.2.43

2023-09-06 10:45

1.2.42

2023-09-06 10:32

1.2.41

2023-09-06 08:13

NEW

  • Tag command

FIXED

  • Nil error in action.pretty

1.2.40

2023-09-06 08:11

1.2.39

2023-09-06 04:25

NEW

  • Add --save NAME to na next to save more complex queries and run with na saved NAME (or just na NAME)
  • na saved --select flag to allow interactive selection of search(es)

IMPROVED

  • Allow na saved --delete to handle multiple arguments
  • Allow wildcards when deleting saved searches
  • Refactor request for input, no change to user experience
  • Refined wildcard (?*) handling
  • When displaying actions wider than the screen, wrap at words and indent 2 spaces from start of action (after prefix)

1.2.38

2023-09-03 11:25

NEW

  • Open the todos database in an editor with na todos --edit
  • A theme file is written to ~/.local/share/na/theme.yaml where you can modify the colors used for all displays
  • Allow tag=~PATTERN comparison for regex matching

IMPROVED

  • Better error message for na next when no todo is matched
  • If STDOUT isn’t a TTY, don’t enable pagination, regardless of global setting
  • Allow –find or –grep as synonyms for –search

FIXED

  • Date tags containing hyphens triggered OR searches because they were initially interpreted as negative tag searches
  • Templating irregularities
  • Error thrown when running without $EDITOR variable defined in environment

1.2.37

2023-09-01 12:42

NEW

  • na undo command to undo last change or last change to file specified in arguments

IMPROVED

  • Disable pagination when using –omnifocus
  • Refactoring codebase
  • --in TODO option for na complete

1.2.36

2023-09-01 12:41

NEW

  • na undo command to undo last change or last change to file specified in arguments

IMPROVED

  • Disable pagination when using –omnifocus
  • Refactoring codebase
  • --in TODO option for na complete

1.2.35

2023-08-30 11:59

IMPROVED

  • If a search string contains @tags and –exact or –regex isn’t specified, the @tags will be extracted and passed as a –tagged search.
  • Tag handling (including values and comparisons) in tags extracted from search strings
  • na complete --project PROJ flag to move to a specific project
  • na restore --project PROJ flag to move restored action to
  • Exit gracefully if tagged command is run with invalid
  • Display action affected when using update command

FIXED

  • Escape search for tokens to allow parenthesis and other

1.2.34

2023-08-30 09:22

NEW

  • na restore SEARCH to remove @done tag from result(s) (aliased as unfinish)

1.2.33

2023-08-29 13:45

NEW

  • na update --edit flag to open a single task in your default $EDITOR for modification and notes
  • Expand natural language dates in recognized date-based tags (@due, @start, @deferred, etc.)
  • Edit command now opens editor on matched action, previous edit

IMPROVED

  • Allow multiple add or remove tags using comma-separated list

FIXED

  • na update --restore irregularities
  • Failing if using gum to input search string

1.2.32

2023-08-29 10:59

FIXED

  • Missing commands

1.2.31

2023-08-29 10:32

FIXED

  • Invalid path for na changelog command

1.2.30

2023-08-29 06:50

NEW

  • na completed to show completed actions with date ranges and search patterns
  • Pagination using system pager

IMPROVED

  • When replacing a priority tag, remove any space before it the action text
  • Restore command decomposition
  • Allow multiple saved searches to be executed at once
  • --restore flag for update command to remove @done tags
  • Pagination for help output

FIXED

  • --done flag not working on na next
  • Missing descriptions in help examples

1.2.29

2023-08-21 11:08

FIXED

  • Reverting subcommand breakup

1.2.28

2023-08-21 11:01

1.2.27

2023-08-21 10:58

NEW

  • na archive --done to archive all @done actions

IMPROVED

  • Split commands into separate files for easier maintenance

1.2.26

2023-08-21 10:26

NEW

  • na finish and na archive subcommands as aliases for equivalant update commands

FIXED

  • –archive flag for na finish

1.2.25

2023-08-21 07:23

FIXED

  • Find command on Linux

1.2.24

2023-06-14 09:16

1.2.23

2023-06-05 10:42

FIXED

  • Actually implement the –template option

1.2.22

2023-06-05 10:35

NEW

  • Global --template PATH option to define a template for new files, can be added to .na.rc

IMPROVED

  • Help verbiage and examples

FIXED

  • Variable assignment warnings

1.2.20

2023-05-09 10:40

FIXED

  • Allow single character projects
  • Allow parens in project title

1.2.19

2023-01-17 16:49

IMPROVED

  • --nest flag creates a flat list with project included in task title, --omnifocus creates OmniFocus-compatible project nesting

1.2.18

2023-01-17 13:38

IMPROVED

  • Format tags OmniFocus wouldn’t recognize as @tags(TAG) in –nest output
  • Include notes in –nest output

1.2.17

2023-01-17 11:23

IMPROVED

  • --nest works with find and tagged
  • --nest creates heirarchy of parent projects, indented TaskPaper style

1.2.16

2023-01-17 10:13

NEW

  • na next --nest will output a TaskPaper format list of actions grouped under their respective files with the filename as the containing project

FIXED

  • Better solution to target_proj nil error

1.2.15

2022-11-28 10:58

FIXED

  • na update error when not moving project

1.2.14

2022-11-12 10:57

NEW

  • na find --tagged allows narrowing search results with tag queries
  • na tagged --search allows narrowing tag results with text search
  • na next accepts –tagged and –search (as well as –exact and –regex) for filtering actions

FIXED

  • Error when a todo file contained a task without a project

1.2.13

2022-11-01 12:43

FIXED

  • Allow colon at end of action without recognizing as project

1.2.12

2022-10-31 13:52

FIXED

  • –save flag for find and tagged not working properly

1.2.11

2022-10-31 13:45

FIXED

  • Frozen string error

1.2.10

2022-10-29 15:59

FIXED

  • Better handling of tokenized search for todo matching with multiple arguments
  • Guard for error parsing project name

1.2.9

2022-10-29 10:50

FIXED

  • Na next with a todo search wasn’t requiring a match

1.2.8

2022-10-28 11:52

IMPROVED

  • Empty lines in notes end a task in the parser
  • Moving a task to the end of a project respects line breaks

FIXED

  • Moving action within same project to end not parsing correctly

1.2.7

2022-10-28 07:29

IMPROVED

  • Code refactoring

FIXED

  • All_req error
  • Adding entries to project names containing hyphen

1.2.6

2022-10-26 10:50

NEW

  • Pass notes to STDIN using piped input when using the --note switch
  • --notes switch for next, find, and tagged to include action notes in output

IMPROVED

  • Update na saved examples and documentation
  • Better handling of unknown commands, affecting na -a ACTION and na SAVED_SEARCH
  • Additional help documentation and examples
  • Updated documentation
  • If a todo query contains only a negative, display all non-matching todos
  • Don’t display readline prompts if not a TTY
  • Prompt hook generator recognizes when a global file is being used and modifies prompt hooks to search for project name or tag based on the value of --cwd_as.

FIXED

  • Debug messages showing when not using –debug

1.2.5

2022-10-26 07:39

FIXED

  • Error with add command

1.2.4

2022-10-26 07:28

FIXED

  • Backup file naming

1.2.3

2022-10-25 17:05

CHANGED

  • Add a preceding dot to backup files created when updating to make backups hidden from notetaking apps and the like.

1.2.2

2022-10-25 14:30

CHANGED

  • na update --done now means “include @done actions in search”
  • na next --in QUERY now searches for a known todo file (formerly required arguments, now both work)

NEW

  • --at [start|end] switch for add and update to determine
  • Global --file PATH flag to specify a single global todo file
  • --add_at [start|end] global flag that can be added to config to make permanent
  • --finish switch for na add to immediately mark an action as @done
  • --cwd_as [project|tag] global flag when using a global --file to determine if the current working directory (last element) is added as an @tag or parent project

IMPROVED

  • Refactor na add to use improved task update code
  • Confirm target file before requesting task when running `na

1.2.1

2022-10-22 10:18

NEW

  • Added --done tag to next/find/tagged to include @done actions in the output
  • Use na changes to view the changelog and see recent changes

IMPROVED

  • You can run na SAVED_SEARCH using any saved search (same as running na saved SAVED_SEARCH but niftier)

1.2.0

2022-10-22 01:32

CHANGED

  • na add --to now specifies a project, --in specifies a todo file
  • Prefer fzf over gum when available

NEW

  • --edit and --delete for saved searches (na saved)
  • na add --todo FILE will match any known todo file when adding an action
  • na add --project PROJ will match any existing project when adding an action
  • na update [options] search string will update an existing task, moving it between projects, adding and removing tags, marking finished, setting priority, adding/replacing notes, or archiving it
  • --tagged TAG flag for na update searches by tag/value
  • na projects will list all projects in a todo file, optional argument to query known todos
  • --delete switch for na update

IMPROVED

  • Include arguments with na edit to narrow down which file to edit (partial matching)
  • Improved handling of todo file search arguments for na next
  • If todo file search returns zero results, loosen search
  • When using !negations in todo matching, allow the negation to match any part of the path, not just last element
  • Full token matching when using na todos QUERY
  • Offer gum and readline fallbacks for fzf menu with na update
  • --overwrite option when adding a note using na update (defaults to append)
  • Allow multiple file selections for na update
  • Display “Inbox” as a parent
  • Ignore @done actions in next and tagged (unless specifically included) but allow them to appear in na find

FIXED

  • na add --priority being interpreted as note
  • Immediately save created todo files to history
  • Multi-line note handling
  • Project regex
  • Error when an action contains a left curly brace
  • Don’t show @done tasks unless specifically searched for

1.1.26

2022-10-15 10:36

IMPROVED

  • A parenthetical at the end of an action will be interpreted as a note. If –note is additionally supplied, entered note is concatenated to parenthetical note.
  • Allow multi-line notes

1.1.25

2022-10-12 08:37

FIXED

  • Unable to search for next action tag with find or tagged

1.1.24

2022-10-12 08:27

FIXED

  • Force utf-8 encoding when reading files, should fix invalid byte sequence errors

1.1.23

2022-10-07 10:02

NEW

  • Saved searches. Add --save TITLE to tagged or find commands to save the parameters for use with na saved TITLE

FIXED

  • Restore wildcard capability of tag searches

1.1.22

2022-10-07 05:58

IMPROVED

  • Help output and code documentation
  • Allow wildcards (* and ?) when matching todo history
  • Allow multiple todo queries separated by comma

FIXED

  • Remove file extension when matching todo history
  • Todo history query failed on exact match

1.1.21

2022-10-07 04:26

NEW

  • na todos will list (and optionally search) known todo files from history

IMPROVED

  • Fuzzier matching of todo file history
  • Help output fixes
  • Code documentation

1.1.20

2022-10-07 03:16

IMPROVED

  • Date comparisons that don’t specify a time are automatically adjusted to “noon” to allow direct comparison of days

1.1.19

2022-10-07 03:06

IMPROVED

  • More help updates
  • Added --or flag to tagged and find to default to OR boolean combination of search terms/tags
  • Special handling for date comparisons to “today”

1.1.18

2022-10-06 17:23

FIXED

  • Update help to match new default AND searches

1.1.17

2022-10-06 17:02

CHANGED

  • Default to AND search with tagged unless a “+” or “!” is specified

1.1.16

2022-10-06 16:47

NEW

  • --in todo/path flag for find and tagged commands to specify a todo file from history

1.1.15

2022-10-06 16:12

CHANGED

  • If no + or ! tokens are given in search, default to AND search for tokens

IMPROVED

  • Better handling of color in search highlighting

FIXED

  • –regex search broken

1.1.14

2022-10-06 12:30

IMPROVED

  • Code cleanup
  • Highlight search terms in results

FIXED

  • Multiple search terms overriding each other

1.1.13

2022-10-06 06:28

IMPROVED

  • When specifying arguments to next, allow paths separated by / to do more exact matching

1.1.12

2022-10-06 05:42

NEW

  • na add -d X to allow adding new actions to todo files in subdirectories
  • You can now perform <>= queries on tag values (na tagged "priority>=3")
  • You can now perform string matches on tag values (na tagged "note*=markdown")
  • You can use --project X to display only actions within a specific project. Specify subprojects with a path, e.g. na/bugs. Partial matches allowed, works with next, find, and tagged
  • Find and tagged recognize * and ? as wildcards
  • –regex flag for find command
  • –invert command (like grep -v) for find
  • -v/–invert for tagged command

IMPROVED

  • Require value 1-9 for –depth option

1.1.11

2022-10-05 08:56

IMPROVED

  • Respect na_tag setting when creating new todo file
  • Code cleanup

1.1.10

2022-10-05 08:19

FIXED

  • When adding a project, don’t use Ruby #capitalize, which downcases the rest of the project name

1.1.9

2022-10-03 12:08

NEW

  • na add --to PROJECT option to add an action to a project other than Inbox. Case insensitive but requires exact project match. Missing project will be created at top of file.

FIXED

  • -t ALT_TAG functionality fixed

1.1.8

2022-10-02 16:40

FIXED

  • na next -t X didn’t replace @na tag in search, but appended to it

1.1.7

2022-10-02 12:20

IMPROVED

  • You can use !token to add negative values to tag/search queries, e.g. na tagged +maybe !waiting

1.1.6

2022-10-02 11:46

CHANGED

  • na find and na tagged now operate on all actions, not just actions tagged @na. If you want to limit to @na actions, just include +na in the query.

1.1.5

2022-10-01 11:32

FIXED

  • Parsing of project hierarchy for an action

1.1.4

2022-09-29 04:17

FIXED

  • Doing reference in help screen for next

1.1.3

2022-09-28 07:12

FIXED

  • na next --tag X not working

1.1.2

2022-09-28 06:37

IMPROVED

  • Detailed instructions after installing prompt hooks

1.1.1

2022-09-28 04:49

CHANGED

  • Belated minor version bump

1.0.6

2022-09-28 04:22

NEW

  • na prompt [show|install] command to help with adding prompt hooks to your shell

1.0.5

2022-09-28 01:53

FIXED

  • A note containing a colon would be recognized as a project line

1.0.4

2022-09-28 01:18

NEW

  • OS agnostic command to open todo file in an editor
  • na init command to generate a new todo file

IMPROVED

  • Output formatting
  • Make directory matching fuzzy for na next
  • –verbose global switch to output debug info

1.0.3

2022-09-27 14:30

FIXED

  • Running na -a -n yielded an error

1.0.2

2022-09-27 14:18

IMPROVED

  • When using gum input, make the input field the width of the terminal

FIXED

  • -a with no arguments will work for backward compatability

1.0.1

2022-09-27 12:52

NEW

  • Add arguments to na next to query previously-seen na files in other directories

1.0.0

2022-09-27 10:45

IMPROVED

  • Initial rewrite from Bash script to Ruby gem
  • Backwards compatibility with the Bash version of NA

Related Projects