Running Tasks

Starting a run

With a .oce file open in the editor, click the Run button (▶) in the editor toolbar, press Ctrl+Enter, or use Run → Run Task File in the menu bar. This adds the file to the run queue. Open Choice then:

1. Parses the task file and resolves aliases
2. Checks that all referenced plugins are installed, enabled, and trusted
3. Executes each task in order, streaming events back to the run panel

To repeat the most recently queued job without switching to that file, press Ctrl+Shift+Enter or use Run → Repeat Last Run from anywhere in the app.

Running a single task block

Each [["..."]] header in the editor has a ▶ Run this task CodeLens button above it. Click it to queue only that block instead of the whole file. The rest of the file is not executed.

When multiple blocks share the same endpoint but have different |label suffixes (e.g. calculate|first and calculate|second), each CodeLens button targets its own block precisely.

Running from a selection

Select any lines in the editor and click the Run selection button in the toolbar (or use the keyboard shortcut shown in the toolbar tooltip). Only the selected text is sent to the plugin — useful for quickly testing a single parameter set without modifying the file.

Scheduled runs

Open the Scheduled Jobs panel to run a task file on a recurring schedule. Each scheduled job has:

• A target .oce file
• A cron expression (e.g. 0 9 * * 1-5 for 9 AM on weekdays)
• An enabled/disabled toggle

The scheduler checks for due jobs every 60 seconds. A job that fires while the app is closed will not be retried — it runs at the next scheduled time.

The run panel

The run panel opens automatically when a task starts. It displays events as they arrive from the plugin.

Event types

Started — The plugin has begun executing the task. Shows the command name and output directory.

Progress — A periodic update from the plugin showing how far through the work it is. Not all plugins emit progress events — some just run and finish.

Artifact created — The plugin has written an output file. The file path is shown and, depending on the file type, a preview or open button appears.

Warning — The plugin encountered a non-fatal issue. Execution continues. Warnings are shown in amber.

Error — The plugin encountered a failure. If stop_on_error is set, subsequent tasks are skipped. Errors are shown in red with a detail panel.

Finished — The task completed. Shows success: true or success: false, elapsed time, and a summary of all artifacts produced.

Reading the output

Each event is expandable. Click an event row to see its full detail JSON — useful for debugging or confirming exact output paths.

Artifacts that are JSON files can often be previewed inline. Other file types show an Open button that opens the file in your system’s default application.

Stop on error

By default, if one task in a file fails, the remaining tasks still run. To change this, add to your .oce file:

[config]
stop_on_error = true

With this set, the first task failure halts the entire file. Tasks that were not yet started are marked as skipped in the run panel.

Run history

Every completed run is recorded. Open the History panel to browse past runs, see their status, and re-open the output files from that run.

What can prevent a run from starting

Plugin not available — The referenced alias does not map to an installed, enabled, trusted plugin. Check the Plugins panel.

Parse error — The .oce file contains invalid TOML, an unrecognised alias format, or a missing required field. The error is shown in the editor with the line number.

Entrypoint missing — The plugin binary is no longer at the path recorded at install time. The plugin will be auto-quarantined. Reinstall to resolve.