Skip to content
v9.1.1
Français

defineCommandTask

import { defineCommandTask } from "@elie-laloum/outpost";

Purpose and behavior

Section titled “Purpose and behavior”

Declare a task that runs a command in a sandbox you opened and keep open; command may be a factory reading dependency values. A nonzero exit status fails the attempt with OutpostError code process, so retry applies. The output is the CommandResult.

Complete example and detailed rules.

Parameters and properties

Section titled “Parameters and properties”
  • optionsRequired
    Omit<TaskOptions<CommandResult>, "perform"> & CommandTaskOptions
    Task scheduling settings, existing sandbox and command or command factory.
  • options.retryOptional
    Retry | undefined
    Retry policy for failed attempts; without it the task runs once. A retried attempt repeats its side effects.
  • options.cacheOptional
    TaskCacheOptions | undefined
    Result cache: a hit restores the stored lossless JSON value with no attempt, usage or side effects. On a miss, a result that is not lossless JSON fails the task. Rejected on gates, interactions and dispatch-result tasks.
  • options.gateOptional
    WorkflowGate | undefined
    Persisted approval or pause definition; execution requires a checkpoint and a matching trusted decision.
  • options.keyRequired
    string
    Unique key in the workflow, matching [A-Za-z0-9][A-Za-z0-9._-]*. Records, events and checkpoints identify the task by it.
  • options.afterOptional
    readonly Task<unknown>[] | undefined
    Tasks that must be done before this one starts, default none; only these can be read with context.value().
  • options.interactionOptional
    TaskInteraction | undefined
    Opt-in durable human-input contract; requires checkpointed scheduling and cannot be combined with a gate.
  • options.conditionOptional
    ((context: TaskContext) => boolean | Promise<boolean>) | undefined
    Evaluated with attempt 0 before the task runs, including when a later start() resumes it; false ends the task as skipped, which skips its dependents.
  • options.timeoutMsOptional
    number | undefined
    Deadline in milliseconds for each attempt, a positive integer up to 2147483647. Expiry aborts context.signal and fails the attempt, which retry may repeat.
  • options.sandboxRequired
    Sandbox
    Existing caller-owned sandbox reused by the task; the task does not close it.
  • options.commandRequired
    Command | ((context: TaskContext) => Command)
    Command to run, or factory that builds it from task dependency values.

Returns

Section titled “Returns”

Task<CommandResult>

Signature

Section titled “Signature”
export declare function defineCommandTask(
  options: Omit<TaskOptions<CommandResult>, "perform"> & CommandTaskOptions,
): Task<CommandResult>;
Section titled “Related contracts”