|
| 1 | +#Tasks CLI |
| 2 | + |
| 3 | +The Coder CLI provides experimental commands for managing tasks programmatically. These are available under`coder exp task`: |
| 4 | + |
| 5 | +```console |
| 6 | +USAGE: |
| 7 | + coder exp task |
| 8 | + |
| 9 | + Experimental task commands. |
| 10 | + |
| 11 | + Aliases: tasks |
| 12 | + |
| 13 | +SUBCOMMANDS: |
| 14 | + create Create an experimental task |
| 15 | + delete Delete experimental tasks |
| 16 | + list List experimental tasks |
| 17 | + logs Show a task's logs |
| 18 | + send Send input to a task |
| 19 | + status Show the status of a task. |
| 20 | +``` |
| 21 | + |
| 22 | +##Creating tasks |
| 23 | + |
| 24 | +```console |
| 25 | +USAGE: |
| 26 | + coder exp task create [flags] [input] |
| 27 | + |
| 28 | + Create an experimental task |
| 29 | + |
| 30 | + - Create a task with direct input: |
| 31 | + |
| 32 | + $ coder exp task create "Add authentication to the user service" |
| 33 | + |
| 34 | + - Create a task with stdin input: |
| 35 | + |
| 36 | + $ echo "Add authentication to the user service" | coder exp task create |
| 37 | + |
| 38 | + - Create a task with a specific name: |
| 39 | + |
| 40 | + $ coder exp task create --name task1 "Add authentication to the user service" |
| 41 | + |
| 42 | + - Create a task from a specific template / preset: |
| 43 | + |
| 44 | + $ coder exp task create --template backend-dev --preset "My Preset" "Add authentication to the user service" |
| 45 | + |
| 46 | + - Create a task for another user (requires appropriate permissions): |
| 47 | + |
| 48 | + $ coder exp task create --owner user@example.com "Add authentication to the user service" |
| 49 | + |
| 50 | +OPTIONS: |
| 51 | + -O, --org string, $CODER_ORGANIZATION |
| 52 | + Select which organization (uuid or name) to use. |
| 53 | + |
| 54 | + --name string |
| 55 | + Specify the name of the task. If you do not specify one, a name will be generated for you. |
| 56 | + |
| 57 | + --owner string (default: me) |
| 58 | + Specify the owner of the task. Defaults to the current user. |
| 59 | + |
| 60 | + --preset string, $CODER_TASK_PRESET_NAME (default: none) |
| 61 | + -q, --quiet bool |
| 62 | + Only display the created task's ID. |
| 63 | + |
| 64 | + --stdin bool |
| 65 | + Reads from stdin for the task input. |
| 66 | + |
| 67 | + --template string, $CODER_TASK_TEMPLATE_NAME |
| 68 | + --template-version string, $CODER_TASK_TEMPLATE_VERSION |
| 69 | +``` |
| 70 | + |
| 71 | +##Deleting Tasks |
| 72 | + |
| 73 | +```console |
| 74 | +USAGE: |
| 75 | + coder exp task delete [flags] <task> [<task> ...] |
| 76 | + |
| 77 | + Delete experimental tasks |
| 78 | + |
| 79 | + Aliases: rm |
| 80 | + |
| 81 | + - Delete a single task.: |
| 82 | + |
| 83 | + $ $ coder exp task delete task1 |
| 84 | + |
| 85 | + - Delete multiple tasks.: |
| 86 | + |
| 87 | + $ $ coder exp task delete task1 task2 task3 |
| 88 | + |
| 89 | + - Delete a task without confirmation.: |
| 90 | + |
| 91 | + $ $ coder exp task delete task4 --yes |
| 92 | + |
| 93 | +OPTIONS: |
| 94 | + -y, --yes bool |
| 95 | + Bypass prompts. |
| 96 | +``` |
| 97 | + |
| 98 | +##Listing tasks |
| 99 | + |
| 100 | +```console |
| 101 | +USAGE: |
| 102 | + coder exp task list [flags] |
| 103 | + |
| 104 | + List experimental tasks |
| 105 | + |
| 106 | + Aliases: ls |
| 107 | + |
| 108 | + - List tasks for the current user.: |
| 109 | + |
| 110 | + $ coder exp task list |
| 111 | + |
| 112 | + - List tasks for a specific user.: |
| 113 | + |
| 114 | + $ coder exp task list --user someone-else |
| 115 | + |
| 116 | + - List all tasks you can view.: |
| 117 | + |
| 118 | + $ coder exp task list --all |
| 119 | + |
| 120 | + - List all your running tasks.: |
| 121 | + |
| 122 | + $ coder exp task list --status running |
| 123 | + |
| 124 | + - As above, but only show IDs.: |
| 125 | + |
| 126 | + $ coder exp task list --status running --quiet |
| 127 | + |
| 128 | +OPTIONS: |
| 129 | + -a, --all bool (default: false) |
| 130 | + List tasks for all users you can view. |
| 131 | + |
| 132 | + -c, --column [id|organization id|owner id|owner name|name|template id|template name|template display name|template icon|workspace id|workspace agent id|workspace agent lifecycle|workspace agent health|initial prompt|status|state|message|created at|updated at|state changed] (default: name,status,state,state changed,message) |
| 133 | + Columns to display in table output. |
| 134 | + |
| 135 | + -o, --output table|json (default: table) |
| 136 | + Output format. |
| 137 | + |
| 138 | + -q, --quiet bool (default: false) |
| 139 | + Only display task IDs. |
| 140 | + |
| 141 | + --status string |
| 142 | + Filter by task status (e.g. running, failed, etc). |
| 143 | + |
| 144 | + --user string |
| 145 | + List tasks for the specified user (username, "me"). |
| 146 | +``` |
| 147 | + |
| 148 | +##Viewing Task Logs |
| 149 | + |
| 150 | +```console |
| 151 | +USAGE: |
| 152 | + coder exp task logs [flags] <task> |
| 153 | + |
| 154 | + Show a task's logs |
| 155 | + |
| 156 | + - Show logs for a given task.: |
| 157 | + |
| 158 | + $ coder exp task logs task1 |
| 159 | + |
| 160 | +OPTIONS: |
| 161 | + -c, --column [id|content|type|time] (default: type,content) |
| 162 | + Columns to display in table output. |
| 163 | + |
| 164 | + -o, --output table|json (default: table) |
| 165 | + Output format. |
| 166 | +``` |
| 167 | + |
| 168 | +##Sending input to a task |
| 169 | + |
| 170 | +```console |
| 171 | +USAGE: |
| 172 | + coder exp task send [flags] <task> [<input> | --stdin] |
| 173 | + |
| 174 | + Send input to a task |
| 175 | + |
| 176 | + - Send direct input to a task.: |
| 177 | + |
| 178 | + $ coder exp task send task1 "Please also add unit tests" |
| 179 | + |
| 180 | + - Send input from stdin to a task.: |
| 181 | + |
| 182 | + $ echo "Please also add unit tests" | coder exp task send task1 --stdin |
| 183 | + |
| 184 | +OPTIONS: |
| 185 | + --stdin bool |
| 186 | + Reads the input from stdin. |
| 187 | +``` |
| 188 | + |
| 189 | +##Viewing Task Status |
| 190 | + |
| 191 | +```console |
| 192 | +USAGE: |
| 193 | + coder exp task status [flags] |
| 194 | + |
| 195 | + Show the status of a task. |
| 196 | + |
| 197 | + Aliases: stat |
| 198 | + |
| 199 | + - Show the status of a given task.: |
| 200 | + |
| 201 | + $ coder exp task status task1 |
| 202 | + |
| 203 | + - Watch the status of a given task until it completes (idle or stopped).: |
| 204 | + |
| 205 | + $ coder exp task status task1 --watch |
| 206 | + |
| 207 | +OPTIONS: |
| 208 | + -c, --column [state changed|status|healthy|state|message] (default: state changed,status,healthy,state,message) |
| 209 | + Columns to display in table output. |
| 210 | + |
| 211 | + -o, --output table|json (default: table) |
| 212 | + Output format. |
| 213 | + |
| 214 | + --watch bool (default: false) |
| 215 | + Watch the task status output. This will stream updates to the terminal until the underlying workspace is stopped. |
| 216 | +``` |
| 217 | + |
| 218 | +>**Note**: The`--watch` flag will automatically exit when the task reaches a terminal state. Watch mode ends when: |
| 219 | +> |
| 220 | +>- The workspace is stopped |
| 221 | +>- The workspace agent becomes unhealthy or is shutting down |
| 222 | +>- The task completes (reaches a non-working state like completed, failed, or canceled) |
| 223 | +
|
| 224 | +##Identifying Tasks |
| 225 | + |
| 226 | +Tasks can be identified in CLI commands using either: |
| 227 | + |
| 228 | +-**Task Name**: The human-readable name (e.g.,`my-task-name`) |
| 229 | + >Note: Tasks owned by other users can be identified by their owner and name (e.g.,`alice/her-task`). |
| 230 | +-**Task ID**: The UUID identifier (e.g.,`550e8400-e29b-41d4-a716-446655440000`) |