Usage

This page contains detailed usage information about every parameter/flag and environment variable that cldr makes use of.

The default usage is cldr <query>. This will try to print the page file of the specified query. However, if cldr is running in plain text mode, no formatting will be printed, and cldr will not try to print the note about the file.

Operations

As of writing this, cldr has the following operations:

PRINT_PAGE,
LIST_OPTIONS,
UPDATE_PAGES,
PRINT_VERSION,
SEARCH_FOR_QUERY,
DELETE_DATABASE,
WRITE_NOTE,
REMOVE_NOTE,
LIST_NOTES,
READ_NOTE

But to see the latest list of operations, check src/operations.h

Parameters/Flags

To see a quick list and description of the flags, look at the usage section of the readme, or run cldr --help.

Otherwise:

-h/--help

cldr (no options specified)
cldr -h/--help

If either of these options are found anywhere within the arguments passed to the program, it will immediately stop parsing arguments and print the help page.

-P/--plain

cldr -P/--plain [other options]

If these are found, cldr will be put in plain text mode. This has various uses depending on the operation (discussed below). But is generally intended to aid in scripting.

-L/--language

cldr -L/--language <language code> [other options]

If these are found, then the following argument will be set as the highest language priority. For the current implementation, the following argument must be at least two characters long, and cannot contain any of the following characters: '/' '$' '`' ' '. To see the current list of available languages (with the default source url), look at the pages.xxx folders in the ethical-tldr repository, where xxx is the language code.

-v/--version

cldr -v/--version [other options]

When this is parsed, cldr will set the operation to PRINT_VERSION, and continue parsing args to look for language flags (see -L, --language).

cldr will then print the version of the program, and the date that the database was updated last.

-p/--platform

cldr -p/--platform <platform> [other options]

When this is parsed, cldr will check if the following argument is one of the available categories set in the src/categories.h file. If it is, then the default platform will be set to the following argument instead of the current OS.

-l/--list | -s/--search

cldr -l/--list [other options]
cldr -s/--search <query> [other options]

When this is parsed, cldr will set the operation to LIST_OPTIONS, and then continue to parse all args, however, if one of the search flags (-s/--search) is found, searching will always take priority, and the operation will be set to SEARCH_FOR_QUERY.

For listing, cldr will then list all of the pages of the highest priority language (see -L/--language, LANGUAGE, and LANG), however, if the platform has been specified (see -p/--platform, TLDR_PLATFORM), cldr will only list the pages of that platform. By default, listing will use a structure like tree to make the information very easy to parse, and will remove the trailing .md from the file name, but if cldr is in plain text, it will simply print the full path to each page.

For searching, all of the information from listing will apply, except cldr will only print entries that contain the query in the file name. For example, cldr --search it sta will only show the files that contain "it-sta" in the file name, such as "git-status" or "git-stash". Additionally, cldr will highlight/color the portion of the file name that matches the query, you can visit the README to see an example of this.

-S/--source

cldr -S/--source <https://example.url/pointing/to/a/zip/file/main.zip> [other options]

When this is parsed, cldr will override the default source (https://codeberg.org/ethical-foss/ethical-tldr/archive/main.zip) with the following argument. This is currently only used when updating the database.

-u/--update

cldr -u/--update [other options]

When this is parsed, cldr will set the operation to UPDATE_PAGES, and then continue parsing all args.

cldr will then download the zip file specified with the source url (see -S/--source). Extract it, remove the old database, move the new files into position, write metadata about the database, and clean up the temporary files created during the process.

-d/--delete

cldr -d/--delete [other options]

When this is parsed, cldr will set the operation to DELETE_DATABSE, and then continue parsing all args.

cldr will then delete the database, you can choose which database by specifying the language.

--no-auto

cldr --no-auto [other options]

When this is parsed, cldr will skip the automatic update check. If used with -u/--update, cldr will not ask if the user would like the database to update automatically, automatically writing it as false.

--colors

cldr --colors

When this is parsed, cldr will print a list of colors that are allowed to be used with the TLDR_COLOR_* environment variables.

-n/--note

cldr -n/--note "message wrapped in quotes" <query>

When this is parsed, cldr will set the operation to WRITE_NOTE, and take the next argument to store it as a string temporarily. cldr will continue parsing args to find a query. Finally, cldr will write a note about the query using the stored string. The message can contain a \n to make a new line, in addition to all of the formatting that's available when reading normal pages, the full explanation of formatting may be too long to describe here, but you can run cldr --help-note to get a full explanation, or you can view src/printHelp.c and look at the printNoteHelp() function to see the explanation that would be printed.

Notes about the <query> will then be automatically read when using cldr <query>.

--list-notes

cldr --list-notes

When this is parsed, cldr will set the operation to LIST_NOTES, and then continue parsing args.

`cldr will then sort of "hijack" the list functionality to list all of the notes you've written.

--read-note

cldr --read-note <query>

When this is parsed, cldr will set the operation to READ_NOTE, and then continue parsing args.

cldr will then read the note about your <query>, but not the <query> page itself. And in plain text mode, any formatting is removed.

--remove-note

cldr --remove-note <query>

When this is parsed, cldr will set the operation to REMOVE_NOTE, and then continue parsing args.

cldr will then try to delete the note about <query>.

--help-note

cldr --help-note

When this is parsed, cldr will print detailed information about how to write and format notes.

--storage-path

cldr --storage-path /path/to/storage [other options]

When this is parsed, cldr will use the specified path to the storage instead of the default "$HOME/.local/share/cldr"

--short

cldr --short [other options]

When this is parsed, cldr will try to only print the short options of pages, compare the output of cldr cldr with cldr cldr --short to see how this functions

--long

cldr --long [other options]

When this is parsed, cldr will try to only print the long options of pages, compare the output of cldr cldr with cldr cldr --long to see how this functions

Environment Variables

DEBUG_LEVEL

DEBUG_LEVEL=<integer> cldr

This sets the logging level of cldr, thus, a log will only be printed if its level is less than the specified value. Negative numbers will be treated as infinity, all logs will be shown. The default value is 0.

LANG/TLDR_LANGUAGE

LANG=es cldr
TLDR_LANGUAGE=es cldr

This functions the same as -L/--language

LANGUAGE

LANGUAGE=es:fr:ja cldr

This sets the priority of languages to try. If a page is not found at the current language, cldr will then try the next language, and so on, until the end of the list.

TLDR_COLOR_*

TLDR_COLOR_*=<color> cldr

This is a set of environment variables (see the list below) that change the formatting for how cldr prints pages. To see the list of available colors, run cldr --colors

TLDR_COLOR_NAME=          # default=blue
TLDR_COLOR_DESCRIPTION=   # default=white
TLDR_COLOR_EXAMPLE=       # default=green
TLDR_COLOR_COMMAND=       # default=red
TLDR_COLOR_PARAMETER=     # default=blue

TLDR_DOWNLOAD_CACHE_LOCATION

TLDR_DOWNLOAD_CACHE_LOCATION="https://example.url" cldr

This functions the same as -S/--source

TLDR_STORAGE_PATH

TLDR_STORAGE_PATH="/path/to/storage" cldr

This functions the same as --storage-path

TLDR_CACHE_MAX_AGE

TLDR_CACHE_MAX_AGE=<integer hours> cldr

This specifies the max age (in hours) a database can be before cldr will try to automatically update it. This is overridden by --no-auto or if the database has been set up to not update automatically.

TLDR_DISABLE_AUTO_UPDATE

TLDR_DISABLE_AUTO_UPDATE=true cldr

This functions the same as --no-auto. Any value other than "true" is discarded.

TLDR_OPTIONS

TLDR_OPTIONS=short|both|long cldr

This functions the same as --short and --long, depending on the input. The default is "both"

TLDR_PLATFORM

TLDR_PLATFORM=<platform> cldr

This functions the same as -p/--platform