Command-line usage

xettel

Main function for the cli interface.

This function sets the config, loads implementations and sets the variables xettel.config.Z_CLASS and xettel.config.ZK_CLASS according to the zk_impl field of the config file.

Args:

config (str): the path to the config file. ~ is expanded. dir (str): the path to the Zettelkasten folder.

xettel [OPTIONS] COMMAND [ARGS]...

Options

-c, --config <config>

config file

-d, --dir <dir>

Zettelkasten directory

count

count zettels matching query

xettel count [OPTIONS] QUERY...

Arguments

QUERY

Required argument(s)

edit

Edit zettel matching query. The query must match exactly one zettel

xettel edit [OPTIONS] IDENTIFIER...

Options

-e, --editor <editor>

editor to write in

Arguments

IDENTIFIER

Required argument(s)

Environment variables

EDITOR

Provide a default for -e

export

export the Zettelkasten to html

xettel export [OPTIONS]

Options

-f, --force

force rewriting all exports

genmap

generate a map of the zettelkasten

xettel genmap [OPTIONS]

gentags

generate tag pages

xettel gentags [OPTIONS]

Options

-d, --delete

delete tag pages that match no zettel

health

check the health of the zettelkasten

xettel health [OPTIONS]

new

Create a new zettel

xettel new [OPTIONS] NAME

Options

-e, --editor <editor>

editor to write in

--noeditor

do not use an editor

--register

register newly created file

-u, --returnuid

return B36 newly created uid (implies –no-editor anf –register)

-t, --template <template>

template for the new file

Arguments

NAME

Required argument

Environment variables

EDITOR

Provide a default for -e

updatedb

update the db from the zettelkasten folder

xettel updatedb [OPTIONS]

Options

-b, --fetchbacklinks

when used together with the option –one, resolvebacklinks as well

-1, --one <one>

only update a single file

-f, --force

force overwriting database

-x, --delete

purge database of files not present anymore

Subcommands

Interfacing with Xapian

xettel updatedb

update the db from the zettelkasten folder

xettel updatedb [OPTIONS]

Options

-b, --fetchbacklinks

when used together with the option –one, resolvebacklinks as well

-1, --one <one>

only update a single file

-f, --force

force overwriting database

-x, --delete

purge database of files not present anymore

In this command, the query is either *, meaning the whole database, or a valid xapian query. Much like notmuch, a query is a string made of prefixed terms or free terms joined together with logical operators OR, AND and so on. Please refer to Xapian documentation for the explicit format of the queries.

Following xettel’s agnostic philosophy, prefixes may be anything, as they are set in the implementations. However, there are a few conventions and some of the prefixes are set in the base class so are always available.

uid

This prefix refers to the UID of a document, its value being a number in base 10 or 36. There is no need to pad it so that it fits in 8 or 12 characters contrarily to filenames. Note however that since searching is done on strings, you may either use a properly formatted UID or a number without leading zeroes. This is a boolean prefix.

text

Searches in the text of Zettels. The prefix is optional.

title

Searches in the title of Zettels.

abstract

Searches in the abstract of Zettels.

tag

Searches among tags. This is a boolean prefix.

filepath

Searches among the file path of the Zettels.

filename

Searches among the file names of the Zettels.

links

Searches the Zettels that link to the provided uid. Conventions follow the same rules as for the prefix uid. This is a boolean prefix.

backlinks

Searches the Zettels that are linked from the provided uid. Conventions follow the same rules as for the prefix uid. This is a booolean prefix.

xettel count

count zettels matching query

xettel count [OPTIONS] QUERY...

Arguments

QUERY

Required argument(s)

Queries are the same as for xettel search.

Editing Zettels

xettel new

Create a new zettel

xettel new [OPTIONS] NAME

Options

-e, --editor <editor>

editor to write in

--noeditor

do not use an editor

--register

register newly created file

-u, --returnuid

return B36 newly created uid (implies –no-editor anf –register)

-t, --template <template>

template for the new file

Arguments

NAME

Required argument

Environment variables

EDITOR

Provide a default for -e

This command generates the new ID for the Zettel with the current time, as YYMMDDHHmmSS and copies the template file to UID-NAME.ext, with the UID in uppercase base 36.

xettel edit

Edit zettel matching query. The query must match exactly one zettel

xettel edit [OPTIONS] IDENTIFIER...

Options

-e, --editor <editor>

editor to write in

Arguments

IDENTIFIER

Required argument(s)

Environment variables

EDITOR

Provide a default for -e

IDENTIFIER is a query that must match a single Zettel.

Exporting

xettel export

export the Zettelkasten to html

xettel export [OPTIONS]

Options

-f, --force

force rewriting all exports

This command calls the export method of implementations. Unless -f is specified, it does not export Zettels if the destination file is newer than the source Zettel.

xettel gentags

generate tag pages

xettel gentags [OPTIONS]

Options

-d, --delete

delete tag pages that match no zettel

This method calls the tag_export class method of implementations.

Graph aspects of a Zettelkasten

xettel health

check the health of the zettelkasten

xettel health [OPTIONS]

This command checks if the Zettelkasten is weakly-connected to the root, i.e. the Zettel with uid 0.

xettel genmap

generate a map of the zettelkasten

xettel genmap [OPTIONS]

This command generates an svg clickable map of the Zettelkasten in the export folder. It uses graphviz in order to do so. Some special tweaking is done for edges between two hubs in order to render the produced map more legible.

If you want for this map to be included in your Zettelkasten, create a new Zettel showing it, for instance:

---
title: Map of the zettelkasten
tags: [meta]
---

<base target='_blank'>
<iframe id="map" src="map.svg">
web browser not supporting svg
</iframe>