CLI Reference

CLI builds are published on GitHub. You can pick and install the correct binary yourself or let a script do it for you.

Bash script:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/oicana/oicana/releases/download/oicana_cli-v0.1.0/oicana_cli-installer.sh | sh

Powershell script:

-ExecutionPolicy Bypass -c "irm https://github.com/oicana/oicana/releases/download/oicana_cli-v0.1.0/oicana_cli-installer.ps1 | iex"

Run oicana -h for a list of all commands and options.

Scaffold a new template

oicana new <name> creates a new directory containing a minimal typst.toml and main.typ. The name doubles as the directory name and the Typst package name, so it must be a valid identifier (letters, digits, _, -; starting with a letter or _).

oicana new invoice
oicana new invoice --version 1.0.0   # default version is 0.1.0

The command refuses to overwrite an existing directory. The generated template passes oicana validate out of the box and is ready for oicana pack.

Package a template

The command oicana pack can package an oicana template to be usable in all supported environments. It will bundle everything in a compressed archive.

While packing, all required dependencies will be bundled into the archive. Packages from the preview namespace are resolved from the local Typst cache, or downloaded from Typst universe if missing. Local packages are resolved from the local package registry. You can install packages with any namespace by copying them in the correct location (see the documentation on template dependencies).

The pack command will follow sym links and include copies of the linked files in the template. When compiling a template with an integration, a template can only read content from its own archive.

The test directory (configured via tool.oicana.tests, defaults to tests/) and the output/ directory are always excluded from the packed template. You can extend the exclusions with the exclude field in your typst.toml manifest:

[package]
name = "invoice"
version = "0.1.0"
entrypoint = "main.typ"
exclude = ["docs/*.pdf", "/assets*/"]

The patterns use gitignore semantics. Patterns are applied recursively by default; prepend / to anchor a pattern to the template root. Defaults are applied first, so a leading ! re-includes them — for example, exclude = ["!/tests/"] packs the test directory anyway. Keep in mind that all files required during compilation need to be packed!

Example commands:

oicana pack - package the template in the current directory
oicana pack templates/invoice - package a specific template
oicana pack -a - package all templates found in the current directory and all child directories
oicana pack -o dist - write the archive to the dist directory instead of the current directory
oicana pack -n {template}-{version}-release.zip - use a custom archive name

The --name (-n) flag supports the following variables:

Variable	Description
`{template}`	Name of the template
`{version}`	Version from the template manifest

Testing

Example commands to test templates:

oicana test - run all tests of the template in the current directory
oicana test templates/invoice - run the tests of the template in the directory templates/invoice
oicana test -a - run all tests of all templates found in the current directory and all child directories
oicana test --watch (or -w) - run tests once, then re-run affected tests whenever a source file changes

Learn more about testing Oicana templates in the testing chapter.

Compilation

For testing purposes, the CLI can compile not-packed Oicana templates. Inputs can be given as relative paths to files.

Example commands to compile templates:

oicana compile -f pdf -j invoice=invoice.json -b logo=oicana.png - compile the template in the current directory to pdf with the given inputs.
oicana compile templates/table -j input=templates/table/data.json - compile the template at templates/table to pdf with the given inputs.
oicana compile templates/table -j input=templates/table/data.json -o out -n output.pdf - same as above, but with a custom output directory and output file name. The defaults are output and {template}.{format} respectively.
oicana compile -d - compile in development mode, which makes development fallback values defined in the template available as inputs.
oicana compile -b logo=company.png -m logo=meta.json - pass metadata for a blob input via a JSON file. Each blob metadata entry (-m) must correspond to a blob value (-b) with the same key.
oicana compile --pdf-standards a-3b - enforce a PDF standard. Multiple standards can be comma-separated (e.g. 2.0,a-4). This overrides any standards configured in the template manifest.

The --name (-n) flag supports the following variables:

Variable	Description
`{template}`	Name of the template
`{version}`	Version from the template manifest
`{timestamp}`	Current timestamp in milliseconds
`{format}`	File extension for the output format, without the leading dot (e.g. `pdf`)

Watch mode

The oicana watch command works like oicana compile, but recompiles the template automatically whenever a source file changes. This includes changes to local Typst packages used by the template.

Example commands:

oicana watch - watch and recompile the template in the current directory
oicana watch templates/invoice -j invoice=invoice.json -b logo=oicana.png - watch a template with inputs

The watch command accepts the same arguments as oicana compile.

Validation

Example commands:

oicana validate - validate the template in the current directory
oicana validate templates/table - validate the manifest of the table template
oicana validate -a - validate all templates found in the current directory and all child directories

If JSON inputs have schemas defined, the validate command will make sure that any default or development values are valid according to the schema. This is the only place these fallback values are checked against their schemas; oicana compile and the integrations only validate explicit input values, because the fallbacks are loaded from inside Typst while schema validation happens outside. Run oicana validate for every template in CI to make sure broken fallbacks do not ship.

Update

oicana update checks for a newer release and replaces the current binary if one is found.

This only works when the CLI was installed through one of the installer scripts. If you installed the binary manually, download the new release from GitHub and replace the binary yourself.