Aliases

An alias is the short name you use in .oce files to refer to an installed plugin. Instead of writing the full plugin ID (com.open-choice.toy-calculator), you write the alias (toy-calculator).

Implied aliases

Every installed plugin automatically gets an implied alias equal to the last segment of its plugin ID. For com.open-choice.toy-calculator, the implied alias is toy-calculator. For com.example.my-analysis-tool, it is my-analysis-tool.

This means that for most plugins, you can use them immediately after installation without any configuration:

[["toy-calculator::calculate"]]
operation = "add"
operands = [1, 2, 3]
output_dir = "./outputs/add"

User-defined aliases

If you have two plugins whose short names conflict, or if you want a shorter or more descriptive name, you can define your own alias in the Aliases panel. Open it from View → Aliases in the menu bar, then click Add alias.

Field	Example
Alias	calc
Plugin ID	com.open-choice.toy-calculator
Version (optional)	0.1.0

After adding this alias, both of the following are equivalent:

[["toy-calculator::calculate"]]   # implied alias
[["calc::calculate"]]             # user-defined alias

User-defined aliases take precedence over implied aliases when there is a conflict.

Pinning a version

An alias can pin a specific plugin version:

[["calc-v1::calculate"]]

Where calc-v1 is a user-defined alias pointing to com.open-choice.toy-calculator version 0.1.0. If you later install 0.2.0, task files using calc-v1 still run against 0.1.0. Task files using the unpinned toy-calculator alias run against whatever version is currently installed.

You can also pin inline in the task key using three segments — but user-defined aliases are clearer for version management.

When an alias cannot be resolved

If a task file references an alias that does not match any installed plugin, the run fails with:

Plugin 'alias-name' is not available (not installed, not trusted, or disabled).

Check that:

1. The plugin is installed — open the Plugins panel and confirm it appears
2. The plugin is enabled — disabled plugins are excluded from the runnable set
3. The plugin is not quarantined
4. The alias matches — implied aliases use the last dot-segment of the plugin ID; check for typos