# CLI reference

> Every carta command-line flag, generated from the binary's own help text.

<!-- Generated by tools/docgen from `carta --man`. Do not edit. -->

Converted by carta

This page is `carta --man` read back in and converted to Markdown by carta itself. Pretty neat!

## Name

carta - Document converter

## Synopsis

**carta** \[**-f**|**--from**] \[**-t**|**--to**] \[**-o**|**--output**] \[**--extract-media**] \[**--resource-path**] \[**--embed-resources**] \[**--self-contained**] \[**--sandbox**] \[**-s**|**--standalone**] \[**--template**] \[**-V**|**--variable**] \[**--wrap**] \[**--columns**] \[**-N**|**--number-sections**] \[**--toc**] \[**--toc-depth**] \[**--mathjax**] \[**--katex**] \[**-M**|**--metadata**] \[**--metadata-file**] \[**-F**|**--filter**] \[**--data-dir**] \[**-c**|**--css**] \[**--epub-cover-image**] \[**--epub-embed-font**] \[**--epub-metadata**] \[**--epub-subdirectory**] \[**--split-level**] \[**--reference-doc**] \[**--highlight-style**] \[**--no-highlight**] \[**--syntax-highlighting**] \[**--syntax-definition**] \[**--list-highlight-languages**] \[**--list-highlight-styles**] \[**--print-highlight-style**] \[**--list-input-formats**] \[**--list-output-formats**] \[**--list-extensions**] \[**-D**|**--print-default-template**] \[**--version**] \[**-h**|**--help**] \[*INPUT*]

## Description

Document converter

## Options

**-f**, **--from** *\<FROM>*\
Input format (e.g. `commonmark`, `json`)

**-t**, **--to** *\<TO>*\
Output format (e.g. `html`, `json`)

**-o**, **--output** *\<OUTPUT>*\
Write output to this file instead of stdout

**--extract-media** *\<DIR>*\
Extract the input's embedded media to this directory, writing each resource as a file and rewriting the document's references to point at the extracted files

**--resource-path** *\<SEARCHPATH>*\
Search these directories, in order, for a document's images and other resources before falling back to the working directory, when a container format embeds them. Directories are separated by the platform's path separator (`:` on Unix, `;` on Windows); repeatable

**--embed-resources**\
Inline a document's referenced media into HTML output as `data:` URIs, producing a self-contained file with no external resource dependencies. Local resources are read from disk (honoring `--resource-path`); references that cannot be read are left as written. Ignored for non-HTML output

**--self-contained**\
Deprecated alias for `--embed-resources --standalone`: produce a self-contained standalone HTML file

**--sandbox**\
Disable network access: remote (`http(s)://`) resources referenced by the document are not fetched. References that would be embedded are left external and a warning is emitted. Use when converting untrusted documents to avoid fetching document-controlled URLs

**-s**, **--standalone**\
Produce a standalone document, wrapping the body in the format's template

**--template** *\<FILE>*\
Render with this template file instead of the format's built-in default; implies `-s`

**-V**, **--variable** *\<KEY\[:VAL]>*\
Set a template variable: `KEY:VAL` (or `KEY=VAL`), or bare `KEY` for `true`. Repeatable; a repeated key accumulates into a list

**--wrap** *\<auto|none|preserve>* \[default: auto]\
Text wrapping in the output: `auto` reflows to the column width, `none` keeps each block on a single line, `preserve` keeps the input's own line breaks

**--columns** *\<N>*\
Column at which `--wrap=auto` reflows text. Defaults to the writer's built-in width

**-N**, **--number-sections**\
Number section headings (`1`, `1.1`, …)

**--toc**\
Include an automatically generated table of contents in the standalone output

**--toc-depth** *\<N>*\
The deepest heading level the table of contents includes (default 3; 1–6)

**--mathjax**\[=*\<URL>*]\
Use MathJax to display embedded TeX math in HTML output. An optional URL overrides the script location

**--katex**\[=*\<URL>*]\
Use KaTeX to display embedded TeX math in HTML output. An optional URL overrides the asset base location

**-M**, **--metadata** *\<KEY\[:VAL]>*\
Set a metadata field: `KEY:VAL` (or `KEY=VAL`; `true`/`false` become booleans), or bare `KEY` for `true`. Repeatable

**--metadata-file** *\<FILE>*\
Read metadata from a YAML or JSON file. Repeatable; later files override earlier ones, and all sit below the document's own metadata

**-F**, **--filter** *\<PROGRAM>*\
Transform the document through this JSON filter before writing: a program that reads the document as JSON on stdin, receives the output format name as its argument, and writes the transformed JSON on stdout. Repeatable; filters run in the order given

**--data-dir** *\<DIR>*\
Search this directory for user data (filters in `filters/`, templates in `templates/`, syntax definitions in `syntax/`) before the built-in locations. Defaults to `$XDG_DATA_HOME/carta` (or `~/.local/share/carta`)

**-c**, **--css** *\<FILE>*\
Style an EPUB with this stylesheet, embedded in the book and linked from every page in place of the built-in one. Repeatable; several sheets are linked in order

**--epub-cover-image** *\<FILE>*\
Use this image as an EPUB's cover, generating a dedicated cover page

**--epub-embed-font** *\<FILE>*\
Embed this font file in an EPUB. Repeatable

**--epub-metadata** *\<FILE>*\
Merge Dublin Core metadata from this XML file into an EPUB's package document

**--epub-subdirectory** *\<DIRNAME>*\
Hold an EPUB's content in this container subdirectory (default `EPUB`; empty for the archive root)

**--split-level** *\<N>*\
Split the document into separate files at this heading level (EPUB). `--epub-chapter-level` is an accepted alias

**--reference-doc** *\<FILE>*\
Style a DOCX from this reference document: its styling parts and document template are reused, and the converted content is generated into it

**--highlight-style** *\<STYLE|FILE>*\
Colorize code blocks with this style: a built-in name (`--list-highlight-styles`) or a JSON theme file. Overrides the style selected by `--syntax-highlighting`

**--no-highlight**\
Leave code blocks unhighlighted (equivalent to `--syntax-highlighting=none`)

**--syntax-highlighting** *\<none|default|idiomatic|STYLE|FILE>*\
How code blocks are presented: `default` colorizes them, `none` leaves them plain, `idiomatic` uses the target format's own listing construct, and any other value names a built-in style or a JSON theme file to colorize with

**--syntax-definition** *\<FILE>*\
Load an additional syntax definition (a KDE-syntax XML file) whose language joins the catalog, overriding a built-in of the same name. Repeatable

**--list-highlight-languages**\
List the languages this build can highlight and exit

**--list-highlight-styles**\
List the built-in highlight styles and exit

**--print-highlight-style** *\<STYLE|FILE>*\
Print a highlight style (a built-in name or a theme file) as a JSON theme and exit

**--list-input-formats**\
List the input formats this build supports and exit

**--list-output-formats**\
List the output formats this build supports and exit

**--list-extensions**\[=*\<FORMAT>*]\
List extensions and their default state for FORMAT (the Markdown dialect if omitted) and exit

**-D**, **--print-default-template** *\<FORMAT>*\
Print the built-in default template for FORMAT and exit

**--version**\
Print version information and exit

**-h**, **--help**\
Print help

\[*INPUT*]\
Read input from this file instead of stdin