CLI reference
Every takumi command and flag, with its default, plus the exit codes and file limits.
takumi --help and takumi <command> --help print the same flags from the binary you have installed.
Commands
| Command | What it does |
|---|---|
takumi image <input> | Renders an HTML file to a PNG, JPEG, WebP, or SVG image. |
takumi pdf <input> | Renders an HTML file to a paged PDF. |
takumi upgrade | Reinstalls takumi from the source Cargo installed it from. |
Commands must be written in full. takumi im is an error, not takumi image.
Global flags
| Flag | Effect |
|---|---|
-q, --quiet | Hides warnings. 1 |
--log <level> | Prints what the render does to standard error, at info or debug. See what a render did. |
-h, --help | Prints help for the command. |
-V, --version | Prints the version. |
1 --quiet still prints errors.
Input and output
takumi image and takumi pdf both take these:
| Flag | Default | Effect |
|---|---|---|
<input> | The HTML file to render, or - for standard input. | |
-o, --output <file> | The file to write, or - for standard output. 1 | |
--list-resources | Lists the files the document would load and whether it may, without rendering. | |
--font <file> | Registers a font file. 2 | |
--root <dir> | The input file's directory, or none for standard input | The directory the document may read. |
--allow-read <dir> | Another directory the document may read. 2 |
1 -o is required unless --list-resources is set.
2 Repeat --font or --allow-read to add more.
takumi image
| Flag | Default | Effect |
|---|---|---|
--width <px> | 1200 | The viewport width in CSS pixels. |
--height <px> | The content's height | The viewport height in CSS pixels. |
--dpr <ratio> | 1 | The device pixel ratio. 1 |
--format <format> | From the output's extension | png, jpeg (or jpg), webp, or svg. 2 |
--quality <0-100> | 75 for JPEG, lossless for WebP | The encoding quality. 3 |
1 The image is width × dpr by height × dpr pixels, and may hold at most 64
megapixels.
2 --format is required with -o -, since standard output has no extension.
3 Setting --quality makes WebP lossy. PNG and SVG ignore it.
takumi pdf
| Flag | Default | Effect |
|---|---|---|
--page <size> | A4 | The page size, as the CSS size property takes it, such as letter landscape or 210mm 297mm. |
--margin <margin> | 1cm, grown to fit a header or footer | The page margins, as the CSS margin property takes them, such as 20mm or 1in 0.75in. |
--pages <ranges> | Every page | The pages to keep, such as 1-3,8 or 5-. 1 |
--header <file> | An HTML file drawn in the top margin of every page. | |
--footer <file> | An HTML file drawn in the bottom margin of every page. | |
--title <title> | The title a PDF viewer shows. | |
--author <name> | An author of the document. 2 | |
--outline | Adds bookmarks for the h1 to h6 headings. | |
--background <color> | A CSS color that fills every page, margins included. |
1 Kept pages keep their numbers from the whole document.
2 Repeat --author to add more authors.
A @page rule in the document wins over --page and --margin. In a header or footer, an element with the class pageNumber or totalPages shows the page number or the page count.
takumi upgrade
| Flag | Effect |
|---|---|
-n, --dry-run | Prints the cargo install command without running it. |
Exit codes
| Code | Meaning |
|---|---|
0 | The output was written, or the listing printed. |
1 | The render failed. |
2 | The command line is wrong. 1 |
3 | The document tried to read a file outside the granted directories. |
1 For example, an unknown flag or command, a value CSS does not accept, or an output format takumi does not write.
Limits
| Limit | Value |
|---|---|
| One file a document loads | 32 MiB |
| All files one render loads | 256 MiB |
| Files one render loads | 1024 |
Nested @import levels | 16 |
Last updated on