Update

Usage

hs update [-h] ID FIELD VALUE

hs update

[ARG [ARG ...]] [--cancel | --revert | --delete] [--remove-tag TAG [TAG ...]] [-w COND [COND ...]] [-t TAG [TAG...]] [-g GROUP] [--order-by FIELD [--desc] --limit NUM] [--failed | --succeeded | --completed | --remaining] [--retries] [--no-confirm]

Description

Update tasks in the database.

Include any number of FIELD=VALUE or tag KEY:VALUE positional arguments.

The -w/--where and -t/--with-tag operate just as in the search command.

Using --cancel marks tasks as cancelled: schedule_time and completion_time are set to now and exit_status to -1. A cancelled task is terminal - it will not be scheduled, retried, or reverted on --restart.

Using --revert reverts everything as if the task was new again.

Using --delete drops the row from the database entirely.

The legacy interface for updating a single task with the ID, FIELD, and VALUE as positional arguments remains valid.

Arguments

ARGS…

Assignment pairs for update.

Options

--cancel

Cancel specified tasks.

Cancelling a task means it will no longer be scheduled. This is done by setting the schedule_time and completion_time to now and the exit_status to -1. The task becomes terminal: it will not be scheduled, retried, or reverted on --restart. A task cannot be cancelled after it is sent to remote clients.

--revert

Revert specified tasks.

A reverted task retains its ID and submit info along with any tags. It will be as if it were new and never scheduled.

--delete

Delete specified tasks.

Deleting a task fully drops the record from the database. All task information will be lost and not recoverable.

--remove-tag TAG…

Strip the specified tag from task records.

-w, --where COND…

List of conditional statements to filter results (e.g., -w 'duration >= 600').

Operators include ==, !=, >=, <=, >, <, ~. The ~ operator applies a regular expression.

-t, --with-tag TAG…

Filter on one or more tags. (e.g., -t special or -t file:a).

Leaving the value unspecified will return any task for which the key exists. Specifying a full key:value pair will match on both.

-g, --group GROUP

Filter matches to a single task group.

-s, --order-by FIELD [--desc]

Order results by field. Optionally, in descending order.

When used in an update command, a --limit is required. For example, to delete the most recently submitted task, --order-by submit_time --desc --limit 1.

-l, --limit NUM

Limit the number of results.

-F, --failed

Alias for -w 'exit_status != 0'.

-S, --succeeded

Alias for -w 'exit_status == 0'.

-C, --completed

Alias for -w 'exit_status != null'.

-R, --remaining

Alias for -w 'exit_status == null'.

--retries

Alias for -w 'attempt > 1' (tasks that have been retried).

-f, --no-confirm

Do not ask for confirmation.

The program first checks the number of affected tasks. The user must confirm the update interactively unless provided with --no-confirm.

Legacy Mode

In previous releases of the software the update command had the following signature. Executing the command with these three positional arguments is still valid.

ID

Unique UUID.

FIELD

Task field name (e.g., “args”).

VALUE

New value.

Use key:value notation for tags. Updating tag will add or update any pre-existing tag with that key.