Usage

## Overview

Tip: At any time you may pass the help option (-h, --help) to Tweego to show its built-in help.

Basic command line usage is as follows: ``` tweego [options] sources… ``` Where [options] are mostly optional configuration flags—see [Options](#usage-options)—and sources are the input sources which may consist of supported files and/or directories to recursively search for such files. Many types of files are supported as input sources—see [File & Directory Handling](#usage-file-and-directory-handling) for more information. ## Options
-a, --archive-twine2
Output Twine 2 archive, instead of compiled HTML.
--archive-twine1
Output Twine 1 archive, instead of compiled HTML.
-c SET, --charset=SET

Name of the input character set (default: "utf-8", fallback: "windows-1252"). Necessary only if the input files are not in either UTF-8 or the fallback character set.

Tip: It is strongly recommended that you use UTF-8 for all of your text files.

-d, --decompile-twee3
Output Twee 3 source code, instead of compiled HTML. See Twee v3 Notation for more information.
--decompile-twee1

Output Twee 1 source code, instead of compiled HTML. See Twee v1 Notation for more information.

Note: Except in instances where you plan to interoperate with Twine 1, it is strongly recommended that you decompile to Twee v3 notation rather than Twee v1.

-f NAME, --format=NAME
ID of the story format (default: "sugarcube-2").
-h, --help
Print the built-in help, then exit.
--head=FILE
Name of the file whose contents will be appended as-is to the <head> element of the compiled HTML.
--list-charsets
List the supported input character sets, then exit.
--list-formats
List the available story formats, then exit.
--log-files

Log the processed input files.

Note: Unsupported when watch mode (-w, --watch) is enabled.

-l, --log-stats

Log various story statistics. Primarily, passage and word counts.

Note: Unsupported when watch mode (-w, --watch) is enabled.

-m SRC, --module=SRC
Module sources (repeatable); may consist of supported files and/or directories to recursively search for such files. Each file will be wrapped within the appropriate markup and bundled into the <head> element of the compiled HTML. Supported files: .css, .js, .otf, .ttf, .woff, .woff2.
--no-trim

Do not trim whitespace surrounding passages—i.e., whitespace preceding and trailing the actual text of the passage. By default, such whitespace is removed when processing passages.

Note: It is recommended that you do not disable passage trimming.

-o FILE, --output=FILE
Name of the output file (default: -; i.e., standard output).
-s NAME, --start=NAME
Name of the starting passage (default: the passage set by the story data, elsewise "Start").
-t, --test
Compile in test mode; only for story formats in the Twine 2 style.
--twee2-compat
Enable Twee2 source compatibility mode; files with the .tw2 or .twee2 extensions automatically have compatibility mode enabled.
-v, --version
Print version information, then exit.
-w, --watch
Start watch mode; watch input sources for changes, rebuilding the output as necessary.
## Basic Examples Compile example_1.twee as example_1.html with the default story format: ``` tweego -o example_1.html example_1.twee ``` Compile all files in example_directory_2 as example_2.html with the default story format: ``` tweego -o example_2.html example_directory_2 ``` Compile example_3.twee as example_3.html with the story format snowman: ``` tweego -f snowman -o example_3.html example_3.twee ``` Compile all files in example_directory_4 as example_4.html with the default story format while also bundling all files in modules_directory_4 into the <head> element of the compiled HTML: ``` tweego -o example_4.html -m modules_directory_4 example_directory_4 ``` Decompile example_5.html as example_5.twee: ``` tweego -d -o example5.twee example5.html ``` ## File & Directory Handling Tweego allows you to specify an arbitrary number of files and directories on the command line for processing. In addition to those manually specified, it will recursively search all directories encountered looking for additional files and directories to process. Generally, this means that you only have to specify the base source directory of your project and Tweego will find all of its files automatically. ### Supported File Extensions Tweego only processes files with the following extensions:
.tw, .twee

Twee notation source files to process for passages.

Note: If any of these files are in the unofficial Twee2 notation, you must manually enable the Twee2 compatibility mode via its command line option (--twee2-compat).

.tw2, .twee2
Unofficial Twee2 notation source files to process for passages. Twee2 compatibility mode is automatically enabled for files with these extensions.
.htm, .html
HTML source files to process for passages, either compiled files or story archives.
.css
CSS source files to bundle.
.js
JavaScript source files to bundle.
.otf, .ttf, .woff, .woff2
Font files to bundle, as @font-face style rules. The generated name of the font family will be the font's base filename sans its extension—e.g., the family name for chinacat.tff will be chinacat.
.gif, .jpeg, .jpg, .png, .svg, .tif, .tiff, .webp

Image files to bundle, as image passages. The generated name of the image passage will be the base filename sans its extension—e.g., the passage name for rainboom.jpg will be rainboom.

Note: As of this writing, image passages are only natively supported by SugarCube (all versions) and the Twine 1 ≥v1.4 vanilla story formats.

.aac, .flac, .m4a, .mp3, .oga, .ogg, .opus, .wav, .wave, .weba

Audio files to bundle, as audio passages. The generated name of the audio passage will be the base filename sans its extension—e.g., the passage name for swamped.mp3 will be swamped.

Note: As of this writing, audio passages are only natively supported by SugarCube ≥v2.24.0.

.mp4, .ogv, .webm

Video files to bundle, as video passages. The generated name of the video passage will be the base filename sans its extension—e.g., the passage name for cutscene.mp4 will be cutscene.

Note: As of this writing, video passages are only natively supported by SugarCube ≥v2.24.0.

.vtt

Text track files to bundle, as text track passages. The generated name of the text track passage will be the base filename sans its extension—e.g., the passage name for captions.vtt will be captions.

Note: As of this writing, text track passages are only natively supported by SugarCube ≥v2.24.0.