Non-core Commands

Non-core commands are all the commands which aren't built into Zet. Zet discovers them dynamically by inspecting $PATH and $ZET_MODULES_PATH. This page lists essential non-core commands distributed with Zet. You can also read their respective help pages by running zet <cmd> --help. You can list all non-core commands available on your system by running zet commands.

zet default-notebook

This command prints current default notebook. You can also change default notebook by running zet default-notebook <notebook-name>.

<notebook-name> is the name of notebook configured in zet.toml, not its path. You can list all currently configured notebooks by running zet notebooks.

zet gen

Generate a file name from a format string. The following format tokens are available:

%u - new UUID¹ (requires uuidgen program installed)
%su - short UUID (8 first characters of UUID; requires uuidgen program installed)
%d - current date and time, with any non-numeric characters being stripped
%r - random number

UUIDs are globally unique indentifiers composed of dash-separated groups of 8-4-4-4-12 hexadecimal characters (i.e. characters from the set of 0-9 and a-f)

Examples

$ zet gen file-%su.txt
file-f391b9a0.txt

zet import

Import files and URLs into the notebook. Imported files are automatically copied to the default notebook. URLs are automatically downloaded and converted by Pandoc into Markdown files.

You can change the default destination of imported files with -d switch.

zet import never overwrites files. If file with a chosen destination already exists, zet import will enumerate it.

Examples

$ zet import https://example.com
https://example.com imported to /home/user/notebooks/0/url.md

$ zet import https://example.com
https://example.com imported to /home/user/notebooks/0/url-1.md

$ zet import ~/some/document.pdf
/home/user/file.pdf imported to /home/user/notebooks/0/document.pdf

$ zet import ~/some/file.pdf -d 0:imported.pdf
/home/user/file.pdf imported to /home/user/notebooks/0/imported.pdf

zet ls

List files inside notebooks. By default all files from all notebooks are listed. This selection can be narrowed down by passing one or more selectors. If any selector expands to a directory, all files in that directory are listed, recursively.

Along file paths, zet ls can also print note titles of known formats by inspecting file contents.

Examples

$ zet ls 0:
0/note.md
0/other-note.md


$ zet ls 0: -t
Note Title::0/note.md
::0/other-note.md

$ zet ls 0:note.md -t -F,
Note Title,0/note.md

Interactive command which ties together several other commands. Shows a list of files inside notebooks, which user can browse, edit or open in external program. List of files can be initially filtered by passing selectors.

zet menu requires fzf to show a searchable list of files. Pressing <enter> prints a selection to standard output, which can be captured in a script and processed further. However, zet menu also allows several actions without exiting the menu. They are bound to the following keys:

<ctrl-e>: edit selected file in the current terminal. ${EDITOR} environment variable is used to determine the editor.
<ctrl-o>: open selected file in external program. xdg-open is used to determine the program which will be used. Typically this opens a new window which is detached from the zet menu process and should outlive it.
<ctrl-f> search currently typed query via zet search. Query may contain any switch accepted by zet search (for example term1 term2 --or). Searches are performed in scope of filtered selectors, but you can extend them by passing additional -s switches. You can also start a query with -- to indicate that from this point only literal arguments will be passed.
<ctrl-r> - reload the initial list of files. It is useful if you made some changes to the files or if you want to show all the files after using the search.

Sort by Frecency

If you have fresort program installed, file list can be sorted by their usage "frecency". To activae this feature, run zet menu --fresort. Files are recognized by their paths so if they are renamed (e.g. with zet mv, their frecency data will be lost.

zet mv

Rename a file. This command accepts either the source and destination selectors, or source selector and --to-title switch, which renames a file to the canonical title.

Canonical title is a note's title converted to the form which is suitable for file names. Typically it is lower-cased, has stripped whitespace and some other special characters.

Renaming can be performed interactively by passing -i switch.

Examples

$ zet mv 0:note.md 0:newname.md
$ zet mv 0:newname.md --to-title -i

zet note

Write new notes in a format preferred by the default_filetype option. Normally zet note opens editor, but it's also possible to add new notes by piping them into zet note --stdin. Notes can be put into templates, which is especially useful for notes piped into zet note.

By default zet note will create a new file. zet note tries to detect note title and name new file accordingly. This happens whenever passed selector (including the default one) points to a directory. Alternatively you can provide a selector with note's destination. If it exists, zet note will append to that file.

You can change the default editor by passing it to --editor switch. It accepts a format string with {} placeholder, which will be replaced with a file path to the temporary note file.

Normally zet note is interactive command which relies on editor being displayed to the user. It means that it is hard to redirect standard output to capture created note's path. That's why zet note provides --and-then switch which executes a command after successful note creation. This command is executed via a shell (sh -c) and it accepts a single placeholder {}, which will be substituted with note's path.

Templates

Templates are ordinary files and can be stored inside a notebook. They're chosen with -t switch which accepts a selector. Template files may contain the following placeholders, which will be automatically substituted when creating the note:

{dt} - current date/time
{host} - hostame of the current system, as reported my hostname program
{user} - name of the current user
{input} - note piped into zet note --stdin

Examples

$ zet note

$ zet note 0:quicknotes.md

$ echo "Hello" | zet note --stdin -t 0:note-template.md

$ zet note --editor='my-editor {}'

$ zet note --and-then 'rsync -av "{}" ssh://example.com/'

zet journal

Create and edit daily journal entries. zet journal opens a file fo the current day. All journal entries are kept in a separate directory, controlled by --journal-directory switch. It accepts a selector pointing to existing or not existing directory.

You can edit journal for different dates by passing an argument to zet journal. It can be either a date in ISO format, or a human-readable date string, like "yesterday" or "last Friday".

Similar to zet note, journal accepts --editor and --template arguments.

Journal templates accept following placeholders:

{date} - current date
{host} - hostame of the current system, as reported my hostname program
{user} - name of the current user

Examples

$ zet journal

$ zet journal -j my-journal-directory

$ zet journal yesterday

$ zet journal last Friday

$ zet journal --editor='my-editor {}'

zet notebooks

List the notebooks, optionally formatted. Format string passed to -f switch accepts the following tokens:

{name} - configured notebook's name
{path} - notebook's path, relative to $ZET_ROOT
{abspath} - notebook's absolute path

zet open

Open notes and files from a notebook. This command accepts a selector with a twist: it might expand to a partial file path, which is examined against all the files. If there is a match, it is opened with the opener program (e.g. xdg-open). If there are many matches, zet open interactively queries which one should it open.

Only the file part of selector is matched against the files.

Default opener can be changed with -p switch. It accepts {} placeholder which will be replaced with actual file path to open.

Examples

$ zet open 0:ot
More than one file matches. Which one to open?
[1] 0/other.md
[2] 0/robots-take-over-the-world.md

zet replace

Finds all occurences of a chosen regular expression and replaces them in-place with a string. Search is performed in all files in all notebooks. Alternatively, selectors can be passed as a third and further arguments to narrow the list of files in which search-replace occurs.

Search can be case-insensitive (-I) and interactive (-i). In interactive mode, zet replace will print a diff with proposed changes in each file, which must be accepted before doing the actual replacement.

Examples

$ zet replace 'some.*text' "other text"
Search-replacing through 14 files...

$ zet replace 'some.*text' "other text" -i
Search-replacing through 14 files...
--- Current version of 0/note.md
+++ After replacement of 0/note.md
@@ -1,2 +1,2 @@
-This is some of my text
+This is other text

>> Accept changes in 0/note.md? ([Y]es / [N]o / [Q]uit)

zet run

Run arbitrary command inside a notebook's directory. Notebook can be changed with -n switch, otherwise a default notebook is used.

Examples

$ zet run git status
On branch master
(...)

$ zet run -n other-notebook bash
user@host$ (input prompt)

zet search

Search the notes for selected queries. Each query is a phrase or regular expression which is expected to match. When more than one query is given, all of them must be present in a file to return a match. --or switch can be used in cases when any of passed queries must be present to return a match.

Search scope can be narrowed down by passing selectors through -s switch. Searches can be performed case-insensitive with -i switch.

zet search uses grep programs found on the system to perform the actual search and presents their output in the unified way. zet search will try to select the fastest available program, but you can enforce one with --grep switch.

zet search will truncate many long matches. You can control this behaviour with --show-all switch.

Examples

$ zet search a e
0/poetry.md:
    I am here
    You are there
    They are everywhere
    This is not a very great poem
    But hopefully someone stops me at some point
(... result truncated, run 'zet search --show-all' to show all matched entries ...)

0/butcher.md:
    Aaaah, fresh meat

$ zet search a y
0/poetry.md:
    They are everywhere
    This is not a very great poem
    But hopefully someone stops me at some point

$ zet search a -l
0/poetry.md
0/butcher.md

$ zet search one two --or
0/ones.md
    one
    one
    certainly not two
    and not the other one

0/twos.md
    two
    two

$ zet search 'regex.*engine' -l -s nb1: -s nb2:
nb1/note.md
nb2/other-note.md

zet show

Show contents of a note inside the terminal, automatically choosing the fanciest formatting program, like less or batcat. You can force using any particular program with -p.

In similar fashion to zet open, zet show accepts a partial selector which interactively queries which file should be opened if partial selector matches more than one.

Implementation detail: zet show is actually only a wrapper for zet open.

Examples

$ zet show glados.md
───────┬────────────────────────────────────────────────────────────────────
       │ File: /home/user/notebooks/0/glados.md
───────┼────────────────────────────────────────────────────────────────────
   1   │ # Glados Anthem
   2   │
   3   │ This was a triumph!
   4   │ I'm making a note here: "HUGE SUCCESS".
   5   │ It's hard to overstate my satisfaction.

$ zet tasks
0/todo.md
---------
- [ ] task 1
    - [ ] subtask

$ zet tasks -s closed
0/todo.md
---------
- [X] finished task