Skip to content
Open Choice

The .oce File Format

A .oce file is a plain-text TOML file that describes one or more tasks to run. Each task specifies a plugin command and its parameters.

Basic structure

A task is declared with a double-bracket header:

[["alias::command"]]
param_key = "value"
other_param = 42
  • alias — the short name for the plugin (see Aliases)
  • command — the command provided by that plugin

Parameters follow on subsequent lines as plain TOML key-value pairs.

Task labels

A |label suffix on the endpoint name gives a block a display name without changing what it runs:

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


[["toy-calculator::calculate|second run"]]
operation = "add"
operands = [4, 5, 6]
output_dir = "./outputs/second"

The label appears in the editor’s ▶ Run this task CodeLens button and in run output. It has no effect on how the plugin executes. Each labelled block is treated as a distinct task and can be run independently.

Version pinning

To lock a specific plugin version for one task block, insert the version between alias and endpoint:

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

If no version is specified, the alias’s default version (set in Aliases settings) is used. Version pinning is useful when you need reproducibility across plugin upgrades.

A complete example

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

This runs the calculate command of the toy-calculator plugin, multiplying 2 × 3 × 4 and writing results to ./outputs/multiply/.

Multiple tasks

Include multiple [[...]] blocks in the same file to run several tasks in sequence:

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


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

Tasks run in the order they appear. If the first task fails, the second still runs by default. To stop on the first failure, add a [config] block:

[config]
stop_on_error = true


[["toy-calculator::calculate"]]
operation = "divide"
operands = [10, 0]
output_dir = "./outputs/divide"


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

With stop_on_error = true, if the divide task errors (division by zero), the add task is skipped.

Parameter types

TOML supports all the types you need:

[["my-plugin::my-command"]]
a_string      = "hello"
a_number      = 42
a_float       = 3.14
a_boolean     = true
an_array      = [1, 2, 3]
string_array  = ["a", "b", "c"]
output_dir    = "./outputs"

Output paths

Most plugins write results to an output_dir you specify. Paths are relative to the .oce file’s location unless they are absolute.

output_dir = "./outputs/my-run"    # relative to the .oce file
output_dir = "C:/data/outputs"     # absolute path

The plugin creates the directory if it does not exist.

File extensions

Open Choice recognises .oce, .ocr, and .toml as task files and treats them identically. Use .oce for files you intend to run regularly, .ocr for saved results you want to keep for reference.

Common mistakes

Forgetting the double brackets

# Wrong — single brackets define a plain TOML table, not a task
["toy-calculator::calculate"]


# Correct
[["toy-calculator::calculate"]]

Using a plugin ID instead of an alias

# Wrong — plugin IDs are not valid as task keys
[["com.open-choice.toy-calculator::calculate"]]


# Correct — use the alias (short name or one you defined)
[["toy-calculator::calculate"]]

See Aliases for a full explanation of the alias system.