From fa82f841c786f77dbd9440779ba579fc014e3193 Mon Sep 17 00:00:00 2001 From: Cian Johnston Date: Wed, 8 Oct 2025 13:43:44 +0100 Subject: [PATCH] chore(docs): add documentation for exp CLI commands (#20019) Updates task documentation with experimental CLI. ~Generated by Claude using `--help` output.~ Should be merged alongside https://github.com/coder/coder/pull/20020 --- cli/exp_task_create.go | 22 ++++ cli/exp_task_delete.go | 14 +++ cli/exp_task_list.go | 26 ++++- cli/exp_task_logs.go | 5 + cli/exp_task_send.go | 11 +- cli/exp_task_status.go | 12 ++- docs/ai-coder/cli.md | 230 +++++++++++++++++++++++++++++++++++++++++ docs/ai-coder/tasks.md | 6 +- 8 files changed, 320 insertions(+), 6 deletions(-) create mode 100644 docs/ai-coder/cli.md diff --git a/cli/exp_task_create.go b/cli/exp_task_create.go index 7aeea13a44..b506d679eb 100644 --- a/cli/exp_task_create.go +++ b/cli/exp_task_create.go @@ -29,6 +29,28 @@ func (r *RootCmd) taskCreate() *serpent.Command { cmd := &serpent.Command{ Use: "create [input]", Short: "Create an experimental task", + Long: FormatExamples( + Example{ + Description: "Create a task with direct input", + Command: "coder exp task create \"Add authentication to the user service\"", + }, + Example{ + Description: "Create a task with stdin input", + Command: "echo \"Add authentication to the user service\" | coder exp task create", + }, + Example{ + Description: "Create a task with a specific name", + Command: "coder exp task create --name task1 \"Add authentication to the user service\"", + }, + Example{ + Description: "Create a task from a specific template / preset", + Command: "coder exp task create --template backend-dev --preset \"My Preset\" \"Add authentication to the user service\"", + }, + Example{ + Description: "Create a task for another user (requires appropriate permissions)", + Command: "coder exp task create --owner user@example.com \"Add authentication to the user service\"", + }, + ), Middleware: serpent.Chain( serpent.RequireRangeArgs(0, 1), ), diff --git a/cli/exp_task_delete.go b/cli/exp_task_delete.go index 361a0cfe7c..43675057bd 100644 --- a/cli/exp_task_delete.go +++ b/cli/exp_task_delete.go @@ -19,6 +19,20 @@ func (r *RootCmd) taskDelete() *serpent.Command { cmd := &serpent.Command{ Use: "delete [ ...]", Short: "Delete experimental tasks", + Long: FormatExamples( + Example{ + Description: "Delete a single task.", + Command: "$ coder exp task delete task1", + }, + Example{ + Description: "Delete multiple tasks.", + Command: "$ coder exp task delete task1 task2 task3", + }, + Example{ + Description: "Delete a task without confirmation.", + Command: "$ coder exp task delete task4 --yes", + }, + ), Middleware: serpent.Chain( serpent.RequireRangeArgs(1, -1), ), diff --git a/cli/exp_task_list.go b/cli/exp_task_list.go index 18b2bec95d..e4d558e35d 100644 --- a/cli/exp_task_list.go +++ b/cli/exp_task_list.go @@ -67,8 +67,30 @@ func (r *RootCmd) taskList() *serpent.Command { ) cmd := &serpent.Command{ - Use: "list", - Short: "List experimental tasks", + Use: "list", + Short: "List experimental tasks", + Long: FormatExamples( + Example{ + Description: "List tasks for the current user.", + Command: "coder exp task list", + }, + Example{ + Description: "List tasks for a specific user.", + Command: "coder exp task list --user someone-else", + }, + Example{ + Description: "List all tasks you can view.", + Command: "coder exp task list --all", + }, + Example{ + Description: "List all your running tasks.", + Command: "coder exp task list --status running", + }, + Example{ + Description: "As above, but only show IDs.", + Command: "coder exp task list --status running --quiet", + }, + ), Aliases: []string{"ls"}, Middleware: serpent.Chain( serpent.RequireNArgs(0), diff --git a/cli/exp_task_logs.go b/cli/exp_task_logs.go index c7224e6185..6c99df3edf 100644 --- a/cli/exp_task_logs.go +++ b/cli/exp_task_logs.go @@ -26,6 +26,11 @@ func (r *RootCmd) taskLogs() *serpent.Command { cmd := &serpent.Command{ Use: "logs ", Short: "Show a task's logs", + Long: FormatExamples( + Example{ + Description: "Show logs for a given task.", + Command: "coder exp task logs task1", + }), Middleware: serpent.Chain( serpent.RequireNArgs(1), ), diff --git a/cli/exp_task_send.go b/cli/exp_task_send.go index c30c3597db..4d9e10bbdd 100644 --- a/cli/exp_task_send.go +++ b/cli/exp_task_send.go @@ -14,8 +14,15 @@ func (r *RootCmd) taskSend() *serpent.Command { var stdin bool cmd := &serpent.Command{ - Use: "send [ | --stdin]", - Short: "Send input to a task", + Use: "send [ | --stdin]", + Short: "Send input to a task", + Long: FormatExamples(Example{ + Description: "Send direct input to a task.", + Command: "coder exp task send task1 \"Please also add unit tests\"", + }, Example{ + Description: "Send input from stdin to a task.", + Command: "echo \"Please also add unit tests\" | coder exp task send task1 --stdin", + }), Middleware: serpent.RequireRangeArgs(1, 2), Options: serpent.OptionSet{ { diff --git a/cli/exp_task_status.go b/cli/exp_task_status.go index f0e1e7b865..a43fd4feed 100644 --- a/cli/exp_task_status.go +++ b/cli/exp_task_status.go @@ -44,7 +44,17 @@ func (r *RootCmd) taskStatus() *serpent.Command { watchIntervalArg time.Duration ) cmd := &serpent.Command{ - Short: "Show the status of a task.", + Short: "Show the status of a task.", + Long: FormatExamples( + Example{ + Description: "Show the status of a given task.", + Command: "coder exp task status task1", + }, + Example{ + Description: "Watch the status of a given task until it completes (idle or stopped).", + Command: "coder exp task status task1 --watch", + }, + ), Use: "status", Aliases: []string{"stat"}, Options: serpent.OptionSet{ diff --git a/docs/ai-coder/cli.md b/docs/ai-coder/cli.md new file mode 100644 index 0000000000..6d337b458d --- /dev/null +++ b/docs/ai-coder/cli.md @@ -0,0 +1,230 @@ +# Tasks CLI + +The Coder CLI provides experimental commands for managing tasks programmatically. These are available under `coder exp task`: + +```console +USAGE: + coder exp task + + Experimental task commands. + + Aliases: tasks + +SUBCOMMANDS: + create Create an experimental task + delete Delete experimental tasks + list List experimental tasks + logs Show a task's logs + send Send input to a task + status Show the status of a task. +``` + +## Creating tasks + +```console +USAGE: + coder exp task create [flags] [input] + + Create an experimental task + + - Create a task with direct input: + + $ coder exp task create "Add authentication to the user service" + + - Create a task with stdin input: + + $ echo "Add authentication to the user service" | coder exp task create + + - Create a task with a specific name: + + $ coder exp task create --name task1 "Add authentication to the user service" + + - Create a task from a specific template / preset: + + $ coder exp task create --template backend-dev --preset "My Preset" "Add authentication to the user service" + + - Create a task for another user (requires appropriate permissions): + + $ coder exp task create --owner user@example.com "Add authentication to the user service" + +OPTIONS: + -O, --org string, $CODER_ORGANIZATION + Select which organization (uuid or name) to use. + + --name string + Specify the name of the task. If you do not specify one, a name will be generated for you. + + --owner string (default: me) + Specify the owner of the task. Defaults to the current user. + + --preset string, $CODER_TASK_PRESET_NAME (default: none) + -q, --quiet bool + Only display the created task's ID. + + --stdin bool + Reads from stdin for the task input. + + --template string, $CODER_TASK_TEMPLATE_NAME + --template-version string, $CODER_TASK_TEMPLATE_VERSION +``` + +## Deleting Tasks + +```console +USAGE: + coder exp task delete [flags] [ ...] + + Delete experimental tasks + + Aliases: rm + + - Delete a single task.: + + $ $ coder exp task delete task1 + + - Delete multiple tasks.: + + $ $ coder exp task delete task1 task2 task3 + + - Delete a task without confirmation.: + + $ $ coder exp task delete task4 --yes + +OPTIONS: + -y, --yes bool + Bypass prompts. +``` + +## Listing tasks + +```console +USAGE: + coder exp task list [flags] + + List experimental tasks + + Aliases: ls + + - List tasks for the current user.: + + $ coder exp task list + + - List tasks for a specific user.: + + $ coder exp task list --user someone-else + + - List all tasks you can view.: + + $ coder exp task list --all + + - List all your running tasks.: + + $ coder exp task list --status running + + - As above, but only show IDs.: + + $ coder exp task list --status running --quiet + +OPTIONS: + -a, --all bool (default: false) + List tasks for all users you can view. + + -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) + Columns to display in table output. + + -o, --output table|json (default: table) + Output format. + + -q, --quiet bool (default: false) + Only display task IDs. + + --status string + Filter by task status (e.g. running, failed, etc). + + --user string + List tasks for the specified user (username, "me"). +``` + +## Viewing Task Logs + +```console +USAGE: + coder exp task logs [flags] + + Show a task's logs + + - Show logs for a given task.: + + $ coder exp task logs task1 + +OPTIONS: + -c, --column [id|content|type|time] (default: type,content) + Columns to display in table output. + + -o, --output table|json (default: table) + Output format. +``` + +## Sending input to a task + +```console +USAGE: + coder exp task send [flags] [ | --stdin] + + Send input to a task + + - Send direct input to a task.: + + $ coder exp task send task1 "Please also add unit tests" + + - Send input from stdin to a task.: + + $ echo "Please also add unit tests" | coder exp task send task1 --stdin + +OPTIONS: + --stdin bool + Reads the input from stdin. +``` + +## Viewing Task Status + +```console +USAGE: + coder exp task status [flags] + + Show the status of a task. + + Aliases: stat + + - Show the status of a given task.: + + $ coder exp task status task1 + + - Watch the status of a given task until it completes (idle or stopped).: + + $ coder exp task status task1 --watch + +OPTIONS: + -c, --column [state changed|status|healthy|state|message] (default: state changed,status,healthy,state,message) + Columns to display in table output. + + -o, --output table|json (default: table) + Output format. + + --watch bool (default: false) + Watch the task status output. This will stream updates to the terminal until the underlying workspace is stopped. +``` + +> **Note**: The `--watch` flag will automatically exit when the task reaches a terminal state. Watch mode ends when: +> +> - The workspace is stopped +> - The workspace agent becomes unhealthy or is shutting down +> - The task completes (reaches a non-working state like completed, failed, or canceled) + +## Identifying Tasks + +Tasks can be identified in CLI commands using either: + +- **Task Name**: The human-readable name (e.g., `my-task-name`) + > Note: Tasks owned by other users can be identified by their owner and name (e.g., `alice/her-task`). +- **Task ID**: The UUID identifier (e.g., `550e8400-e29b-41d4-a716-446655440000`) diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md index 78b9a9adbc..878c542350 100644 --- a/docs/ai-coder/tasks.md +++ b/docs/ai-coder/tasks.md @@ -63,7 +63,7 @@ data "coder_parameter" "setup_script" { # The Claude Code module does the automatic task reporting # Other agent modules: https://registry.coder.com/modules?search=agent -# Or use a custom agent: +# Or use a custom agent: module "claude-code" { source = "registry.coder.com/coder/claude-code/coder" version = "3.0.1" @@ -128,6 +128,10 @@ Coder can automatically generate a name your tasks if you set the `ANTHROPIC_API If you tried Tasks and decided you don't want to use it, you can hide the Tasks tab by starting `coder server` with the `CODER_HIDE_AI_TASKS=true` environment variable or the `--hide-ai-tasks` flag. +## Command Line Interface + +See [Tasks CLI](./cli.md). + ## Next Steps