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]
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
search
search in the database
xettel search [OPTIONS] QUERY...
Options
- -o, --output <output>
output options
- Options
normal | uid | tags | filename | backlinks | map | json
- -s, --sort
sort by most recent
- -n, --number <number>
Number of items to query for
Arguments
- QUERY
Required argument(s)
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
xettel search
search in the database
xettel search [OPTIONS] QUERY...
Options
- -o, --output <output>
output options
- Options
normal | uid | tags | filename | backlinks | map | json
- -s, --sort
sort by most recent
- -n, --number <number>
Number of items to query for
Arguments
- QUERY
Required argument(s)
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.
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>