CLI Reference

This documentation is generated from the output of notesdir -h.

usage: notesdir [-h] {info,query,new,change,mv,organize,backfill,tags,relink} ...

Sub-commands:

info

Show info about a file, such as metadata and links/backlinks.

notesdir info [-h] [-f FIELDS] [-j] path

Positional Arguments

path

Named Arguments

-f, --fields

Comma-separated list of fields to show. Possible fields are: path, links, tags, title, created, backlinks. By default, all fields are shown.

-j, --json

Output as JSON.

Default: False

query

Query for files. For full query syntax, see the documentation of notesdir.models.FileQuery.parse - an example query is “tag:foo sort:title,-created”.

notesdir query [-h] [-f FIELDS] [-j | -t] [query]

Positional Arguments

query

Query string. If omitted, the query matches all files.

Named Arguments

-f, --fields

Comma-separated list of fields to show. Possible fields are: path, links, tags, title, created, backlinks. Not all fields are shown by default.

-j, --json

Output as JSON.

Default: False

-t, --table

Format output as a table.

Default: False

new

Create new file from a Mako template. You can either specify the path to the template, or just give its name without file extensions if it is listed in “templates” in your ~/notesdir.conf.py file. This command will print the path of the newly created file.

notesdir new [-h] [-p] template [dest]

Positional Arguments

template

Name or path of template.

dest

Suggested destination filename. This may be overridden by the template, or adjusted if it conflicts with an existing file. A filename will be selected for you if omitted.

Named Arguments

-p, --preview

Print plan but do not create file

Default: False

change

Update metadata of the specified files.

notesdir change [-h] [-a ADD_TAGS] [-d DEL_TAGS] [-t TITLE] [-c CREATED] [-p] paths [paths ...]

Positional Arguments

paths

Files to update.

Named Arguments

-a, --add-tags

Comma-separated list of tags to add (if not already present).

-d, --del-tags

Comma-separated list of tags to remove (if present).

-t, --title

New title for files

-c, --created

New created datetime for files, in ISO8601 format

-p, --preview

Print changes to be made but do not change files

Default: False

mv

Move a file. Any links to the file from other files in your configured notes directories will be updated to point to the new location, provided the referrers are of supported file types. Relative links from this file to other files will also be updated, if this file is of a supported file type.

notesdir mv [-h] [-j] [-p] src dest

Positional Arguments

src

File or folder to move.

dest

New file path or new parent folder. If the argument is a folder, notesdir will try to keep the original filename. In either case, this command will not overwrite an existing file; it will adjust the new filename if needed to be unique within the target directory.

Named Arguments

-j, --json

Output as JSON. The output is an object whose keys are the paths of files that were moved, and whose values are the new paths of those files.

Default: False

-p, --preview

Print changes to be made but do not move or change files

Default: False

organize

Organize files. All files within the directories configured in conf.repo_conf.root_paths will be passed to the function defined in conf.path_organizer, and will be moved if it returns a new path. New folders will be created when necessary and empty folders will be deleted. As with the mv command, relative links between files will be updated, if the file type of the referrer is supported.

notesdir organize [-h] [-j] [-p]

Named Arguments

-j, --json

Output as JSON. The output is an object whose keys are the paths of files that were moved, and whose values are the new paths of those files.

Default: False

-p, --preview

Print changes to be made but do not move or change files

Default: False

backfill

Backfill missing metadata. All files within the directories configured in conf.repo_conf.root_paths will be checked for title and created date metadata. If the title is missing, a title is set based on the filename; if created is missing, it is set based on the file’s birthtime or ctime. Errors will be printed but will not result in a nonzero return status, since it is expected that some files in your notes directories will not be supported by notesdir.

notesdir backfill [-h] [-p]

Named Arguments

-p, --preview

Print changes to be made but do not change files

Default: False

tags

Show a list of tags and the number of files that have each tag.

notesdir tags [-h] [-j] [query]

Positional Arguments

query

Query to filter files by. If omitted, data for all files is shown. The query format is the same as for the query command.

Named Arguments

-j, --json

Output as JSON. The output is an object whose keys are tags and whose values are the number of notes that matched the query and also possess that tag.

Default: False