> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/talus-docs-v2.1.0/reference/cli/task.md). # nexus task **Audience:** Nexus CLI users and integrators. **Command:** `nexus task`. **Generated from:** Nexus CLI `v2.1.0` release executable (`nexus task --help` and each subcommand's `--help`; generated — do not hand-edit). > **Before acting on rejection or timeout:** Verify matching bindings, package IDs, and transaction effects on the selected network. A hosted projection that omits `Rejected { reason }`, `TaskRejectedEvent`, or exact Invocation timeout identity does not justify inferring rejection from a failed submission. This page is the complete help tree for `nexus task`. Global output flags can appear after the family or nested subcommand. ### Invocation timeout boundary The CLI accepts optional `--invocation-id ` to refund the exact Invocation before aborting. Omit it only when the command proves one unique candidate; pass the exact ID whenever a lock is known, and stop if multiple candidates cannot be resolved safely. The effective timeout is the configured Tool timeout plus the five-second leader-evaluation buffer, and permissionless recovery begins at twice that effective value. After the transaction, inspect the Invocation, Task, Occurrence, Execution, payment state, and effects. An Invocation timeout refund or Execution abort does not guarantee that the owning occurrence is settled. When the selected build exposes the command, run `nexus task occurrence settle --task-id --occurrence-id `, re-read the occurrence, verify `settled` and zero in-flight work, and only then close the Task. #### Permanent-rejection boundary Inspect the Task’s `Rejected { reason }` value, `TaskRejectedEvent`, and `OccurrenceWithdrawalReason::TaskRejected` before claiming permanent rejection; the rejected proposal has no Execution ID, and its rejection-maintenance gas is deducted from the Task reserve up to the remaining balance. Wait until the schedule and in-flight obligations drain, then use the controller-authorized `task close` path to return the remaining reserve. If a hosted view omits the rejection decoder, use CLI/SDK object and effect reads; do not invent a flag or infer rejection from a failed submission or unavailable leader. #### Input JSON encoding `--input-json` accepts the existing shorthand JSON: an ordinary value becomes one inline value and an array becomes inline many. To pass a typed NexusData value directly, use an exact one-key object with `one` or `many` whose inner value(s) include `kind` (`object`, `data`, or `walrus`). A lookalike ordinary single-key object without that inner `kind` remains inline shorthand; arrays also remain inline many. #### `nexus task` Inline timing sources are additive: the mixed example below creates one standalone occurrence at the current Sui Clock, a second standalone occurrence at `2000000000000`, and one recurrence whose first start defaults to the current Clock with a 60,000 ms interval. `--schedule-file` is the mutually exclusive replacement for inline timing sources. ``` Task -> Occurrence -> Execution A Task owns reusable work, funding, controller authority, and one Schedule. A Schedule contains standalone occurrences and at most one recurrence. An Occurrence is one scheduling opportunity and has a permanent record under its Task. Dispatch creates a deterministic Execution that contains the runtime walks and failure trace. Commands: task create Creates an empty Task for later composition. task schedule Creates and schedules atomically in one transaction. task list Lists Tasks discoverable through owned TaskPointer objects. Lifecycle commands: task inspect Reads Task state and occurrence counts. task pause Stops future dispatch while retaining work. task resume Resumes retained work. task cancel Withdraws future work and retains history. task close Releases resources after live work is complete. task occurrence --help Lists observation and recovery commands. Use --now to schedule at the current Sui Clock time. Task inspection and occurrence inspection read durable object state. Examples: nexus task create --dag-id 0x42 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 nexus task schedule --dag-id 0x42 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 --now nexus task schedule --dag-id 0x42 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 \ --now --at-ms 2000000000000 \ --recurrence-interval-ms 60000 nexus task schedule --dag-id 0x42 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 \ --schedule-file schedule.json nexus task list --limit 50 nexus task inspect --task-id 0x123 nexus task occurrence list --task-id 0x123 --json nexus task occurrence inspect --task-id 0x123 --occurrence-id 7 Usage: nexus task [OPTIONS] Commands: create Create and share an empty Task schedule Create a Task with a complete Schedule list List Tasks owned by the configured signer inspect Inspect current Task object state pause Pause future Task dispatch resume Resume retained Task work cancel Cancel future Task work refill Add MIST to the Task reserve close Release live Task resources occurrence Operate permanent Task occurrences recurrence Set or clear the Task recurrence help Print this message or the help of the given subcommand(s) Options: -h, --help Print help (see a summary with '-h') Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task create` ``` Creates and shares an empty Task. No occurrence is allocated. Outcome: The command returns a Task receipt. Add work later with `task occurrence add` or `task recurrence set`. Funding: Unless --agent-funded is used, the reserve is withdrawn from the signer Sui address balance. Inspect and fund it with `nexus gas balance` and `nexus gas deposit --amount `. Example: nexus task create --dag-id 0x42 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 Usage: nexus task create [OPTIONS] --prepay-amount-mist --occurrence-budget-mist <--dag-id |--agent-id > Options: --scheduler-package Scheduler package used to create the Task -h, --help Print help (see a summary with '-h') Operation: -d, --dag-id Published DAG for default operation or optional Agent selection --agent-id Agent object whose registered skill performs the work; requires --skill-id --skill-id Registered Agent skill identifier; requires --agent-id --authorization-binding Bind a DAG vertex that requires a grant to its recipient object; repeat for each vertex -e, --entry-group DAG entry group used by every occurrence [default: _default_group] Funding: --agent-funded Use the selected Agent vault and Agent control --refund-recipient
Recipient of unused address funded reserve --prepay-amount-mist MIST placed in the Task reserve; address funding uses the signer Sui address balance --occurrence-budget-mist Maximum MIST available to each occurrence Inputs: -i, --input-json Input JSON used by every occurrence -r, --remote Input fields committed to configured remote storage Policy: --pause-on-failure Pause the Task after an unsuccessful settlement Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task schedule` ``` Creates a Task, applies a complete nonempty Schedule, and shares the Task in one transaction. At least one standalone occurrence or recurrence is required. Outcome: The command returns the Task identifier, transaction reference, and every occurrence allocated by the transaction. Funding: Unless --agent-funded is used, the reserve is withdrawn from the signer Sui address balance. Inspect both balance stores with `nexus gas balance`. Move MIST from an owned SUI coin with `nexus gas deposit --amount `. Authorization: Agent skills with onchain Tools that require grants must bind every such DAG vertex to its recipient with repeatable --authorization-binding values. Examples: nexus task schedule --dag-id 0x42 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 --now nexus task schedule --dag-id 0x42 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 \ --after-ms 30000 \ --deadline-after-ms 60000 --priority-fee-percentage 20 nexus task schedule --dag-id 0x42 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 \ --recurrence-interval-ms 60000 --recurrence-occurrences 10 nexus task schedule --agent-id 0x42 --skill-id 0 \ --authorization-binding check_message=0x43 \ --prepay-amount-mist 500000000 \ --occurrence-budget-mist 500000000 --now Usage: nexus task schedule [OPTIONS] --prepay-amount-mist --occurrence-budget-mist <--dag-id |--agent-id > <--schedule-file |--now|--at-ms |--after-ms |--recurrence-interval-ms |--deadline-at-ms |--deadline-after-ms |--priority-fee-percentage |--recurrence-at-ms |--recurrence-after-ms |--recurrence-occurrences |--recurrence-deadline-at-ms |--recurrence-deadline-after-ms |--recurrence-priority-fee-percentage > Options: --scheduler-package Scheduler package used to create the Task -h, --help Print help (see a summary with '-h') Operation: -d, --dag-id Published DAG for default operation or optional Agent selection --agent-id Agent object whose registered skill performs the work; requires --skill-id --skill-id Registered Agent skill identifier; requires --agent-id --authorization-binding Bind a DAG vertex that requires a grant to its recipient object; repeat for each vertex -e, --entry-group DAG entry group used by every occurrence [default: _default_group] Funding: --agent-funded Use the selected Agent vault and Agent control --refund-recipient
Recipient of unused address funded reserve --prepay-amount-mist MIST placed in the Task reserve; address funding uses the signer Sui address balance --occurrence-budget-mist Maximum MIST available to each occurrence Inputs: -i, --input-json Input JSON used by every occurrence -r, --remote Input fields committed to configured remote storage Policy: --pause-on-failure Pause the Task after an unsuccessful settlement Schedule: --schedule-file Read the complete Schedule from a JSON file Timing: --now Add one occurrence at the current Sui Clock time --at-ms Add an occurrence at an absolute millisecond timestamp --after-ms Add an occurrence after an offset from one Sui Clock read --deadline-at-ms Use one absolute deadline for inline standalone occurrences --deadline-after-ms Set each standalone deadline from its resolved start --priority-fee-percentage Set the priority fee for inline standalone occurrences Recurrence: --recurrence-interval-ms Add a recurrence with this millisecond interval --recurrence-at-ms Start the recurrence at an absolute timestamp --recurrence-after-ms Start the recurrence after an offset from the Sui Clock --recurrence-occurrences Limit the total recurring occurrences --recurrence-deadline-at-ms Use one absolute deadline for the first recurring occurrence --recurrence-deadline-after-ms Set recurring deadlines from each resolved start --recurrence-priority-fee-percentage Set the priority fee for recurring occurrences Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task list` ``` List Tasks owned by the configured signer Usage: nexus task list [OPTIONS] Options: --scheduler-package Scheduler package that defines TaskPointer --cursor Opaque cursor returned by the previous page --limit Maximum TaskPointer objects read from one RPC page [default: 50] -h, --help Print help Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task inspect` ``` Inspect current Task object state Usage: nexus task inspect [OPTIONS] --task-id Options: -t, --task-id Task object ID -h, --help Print help Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task pause` ``` Pause future Task dispatch Usage: nexus task pause [OPTIONS] --task-id Options: -t, --task-id Task object ID -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task resume` ``` Resume retained Task work Usage: nexus task resume [OPTIONS] --task-id Options: -t, --task-id Task object ID -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task cancel` ``` Cancel future Task work Usage: nexus task cancel [OPTIONS] --task-id Options: -t, --task-id Task object ID -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task refill` ``` Add MIST to the Task reserve Usage: nexus task refill [OPTIONS] --task-id --amount-mist Options: -t, --task-id Task object ID --amount-mist MIST added to the Task reserve -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task close` ``` Release live Task resources Usage: nexus task close [OPTIONS] --task-id Options: -t, --task-id Task object ID -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task occurrence` ``` An Occurrence is the permanent scheduler record for one opportunity to run a Task. After dispatch it references a deterministic Execution with the detailed runtime history. Lifecycle: pending Waiting to be offered for dispatch. advertised Offered to leaders. Use expire only after its deadline. executing Runtime work is active. Inspect the Execution for progress. finished Runtime work ended. Settle the occurrence into its Task. settled Scheduler processing and refund accounting are complete. missed The dispatch deadline elapsed before dispatch. withdrawn Future work was removed before dispatch. Observation: nexus task occurrence inspect --task-id 0x21 --occurrence-id 7 nexus task occurrence cost --task-id 0x21 --occurrence-id 7 nexus execution inspect --task-id 0x21 --occurrence-id 7 Recovery: nexus task occurrence settle --task-id 0x21 --occurrence-id 7 nexus task occurrence expire --task-id 0x21 --occurrence-id 7 nexus task occurrence abort-expired --task-id 0x21 --occurrence-id 7 Use inspect --follow to wait until an action is required or lifecycle processing is complete. Usage: nexus task occurrence [OPTIONS] Commands: list List permanent occurrence records add Add one standalone occurrence inspect Inspect one permanent occurrence record settle Settle a finished runtime object into its Task record expire Record an advertised occurrence as missed after its deadline cost Inspect occurrence payment, locks, and refund state abort-expired Abort runtime work after its workflow timeout help Print this message or the help of the given subcommand(s) Options: -h, --help Print help (see a summary with '-h') Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task occurrence list` ``` List permanent occurrence records Usage: nexus task occurrence list [OPTIONS] --task-id Options: -t, --task-id Task object ID --cursor Opaque cursor returned by the previous page --limit Maximum dynamic fields read from one RPC page [default: 50] -h, --help Print help Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task occurrence add` ``` Adds one standalone occurrence to an existing Task. Timing: With no timing option, the occurrence starts at the current Sui Clock time. Use --at-ms for an absolute time or --after-ms for an offset from the Clock. Outcome: The receipt identifies the new occurrence and gives its inspect command. Usage: nexus task occurrence add [OPTIONS] --task-id Options: -t, --task-id Task object ID -h, --help Print help (see a summary with '-h') Timing: --now Use the current Sui Clock time; this is the default --at-ms Use an absolute millisecond start timestamp --after-ms Use an offset from the current Sui Clock --deadline-at-ms Use an absolute dispatch deadline --deadline-after-ms Set the deadline from the resolved start --priority-fee-percentage Set the dispatch priority fee percentage [default: 20] Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task occurrence inspect` ``` Inspect one permanent occurrence record Usage: nexus task occurrence inspect [OPTIONS] --task-id --occurrence-id Options: -t, --task-id Task object ID --occurrence-id Occurrence number within the Task --follow Poll until an action is required or processing is complete --timeout-secs Maximum observation time; default is 3600 --poll-ms Delay between reads; default is 1000 -h, --help Print help Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task occurrence settle` ``` Settle a finished runtime object into its Task record Usage: nexus task occurrence settle [OPTIONS] --task-id --occurrence-id Options: -t, --task-id Task object ID --occurrence-id Occurrence number within the Task -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task occurrence expire` ``` Record an advertised occurrence as missed after its deadline Usage: nexus task occurrence expire [OPTIONS] --task-id --occurrence-id Options: -t, --task-id Task object ID --occurrence-id Occurrence number within the Task -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task occurrence cost` ``` Inspect occurrence payment, locks, and refund state Usage: nexus task occurrence cost [OPTIONS] --task-id --occurrence-id Options: -t, --task-id Task object ID --occurrence-id Occurrence number within the Task -h, --help Print help Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task occurrence abort-expired` ``` Abort runtime work after its workflow timeout Usage: nexus task occurrence abort-expired [OPTIONS] --task-id --occurrence-id Options: -t, --task-id Task object ID --occurrence-id Occurrence number within the Task --invocation-id Refund this exact Invocation before aborting -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task recurrence` ``` Set or clear the Task recurrence Usage: nexus task recurrence [OPTIONS] Commands: set Set or replace the Task recurrence clear Clear future recurring work help Print this message or the help of the given subcommand(s) Options: -h, --help Print help Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task recurrence set` ``` Set or replace the Task recurrence Usage: nexus task recurrence set [OPTIONS] --task-id --interval-ms Options: -t, --task-id Task object ID -h, --help Print help Timing: --now Use the current Sui Clock time; this is the default --at-ms Use an absolute millisecond start timestamp --after-ms Use an offset from the current Sui Clock --deadline-at-ms Use an absolute dispatch deadline --deadline-after-ms Set the deadline from the resolved start --priority-fee-percentage Set the dispatch priority fee percentage [default: 20] Recurrence: --interval-ms Interval between recurring occurrences --occurrences Total recurring occurrences, omitted for no limit Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` #### `nexus task recurrence clear` ``` Clear future recurring work Usage: nexus task recurrence clear [OPTIONS] --task-id Options: -t, --task-id Task object ID -h, --help Print help Gas: -g, --sui-gas-coin Optional owned gas coin object ID. Most commands use address balance gas when omitted. -b, --sui-gas-budget Maximum MIST spent on Sui transaction gas. [default: 100000000] Output: --json Emit machine readable JSON -v, --verbose... Increase diagnostic detail -q, --quiet... Show errors only ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.talus.network/talus-docs-v2.1.0/reference/cli/task.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.