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-alpha.11/oicana_cli-installer.sh | sh

Powershell script:

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

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

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.

By default, the test directory (configured via tool.oicana.tests, defaults to tests/) and the output/ directory are excluded from the packed template. You can customize which files are excluded using 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. Keep in mind that all files required during compilation need to be packed!

For a list of all command options, run oicana pack -h.

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

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.

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

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

E.g. oicana validate templates/table will validate the manifest of the table template.

If JSON inputs have schemas defined, the validate command will make sure that any default or development values are valid according to the schema.