Provide better documentation and structure to EA workflow commands (#235)

* First pass

* Update docs

* Move run commands under unified command

* Move to singular

* Update command structure

* Back to plural

Author: mdbenjam

cmd/root.go

@@ -96,19 +96,19 @@ func isCI() bool {
 
 func setupWorkflowCommands(deps *dependencies.Dependencies) {
 	deps.Commands.Workflow.TaskListCmd = NewTaskListCmd(deps)
-	deps.Commands.Workflow.TaskRunCmd = NewTaskRunCmd(deps)
+	deps.Commands.Workflow.TaskRunCmd = NewTaskRunStartCmd(deps)
 	deps.Commands.Workflow.TaskRunListCmd = NewTaskRunListCmd(deps)
 	deps.Commands.Workflow.TaskRunDetailsCmd = NewTaskRunDetailsCmd(deps)
 	deps.Commands.Workflow.VersionListCmd = NewVersionListCmd(deps)
 	deps.Commands.Workflow.VersionReleaseCmd = NewVersionReleaseCmd(deps)
 	deps.Commands.Workflow.WorkflowListCmd = workflowListCmd
 
 	taskCmd.AddCommand(deps.Commands.Workflow.TaskListCmd)
-	taskCmd.AddCommand(deps.Commands.Workflow.TaskRunCmd)
-	taskCmd.AddCommand(deps.Commands.Workflow.TaskRunListCmd)
+	taskRunCmd.AddCommand(deps.Commands.Workflow.TaskRunCmd)
+	taskRunCmd.AddCommand(deps.Commands.Workflow.TaskRunListCmd)
+	taskRunCmd.AddCommand(deps.Commands.Workflow.TaskRunDetailsCmd)
 	versionCmd.AddCommand(deps.Commands.Workflow.VersionListCmd)
 	versionCmd.AddCommand(deps.Commands.Workflow.VersionReleaseCmd)
-	deps.Commands.Workflow.TaskRunCmd.AddCommand(deps.Commands.Workflow.TaskRunDetailsCmd)
 }
 
 func setupLogCommands(deps *dependencies.Dependencies) {

cmd/task.go

@@ -28,12 +28,35 @@ const defaultTaskAPIPort = 8120
 
 var taskCmd = &cobra.Command{
 	Use:   "tasks",
-	Short: "Task commands",
+	Short: "Manage tasks",
 }
 
 var taskDevCmd = &cobra.Command{
-	Use:   "dev",
-	Short: "Start a task in development mode",
+	Use:   "dev -- <command to start a workflow service>",
+	Short: "Start a workflow service in development mode",
+	Long: `Start a workflow service in development mode for local testing.
+
+This command runs your workflow service locally on port 8120, allowing you to list and run
+tasks without deploying to Render. Task runs and their logs are stored in memory, so you
+can query them after tasks complete.
+
+The command will spawn a new subprocess with your specified command whenever it needs to
+run a task or list the defined tasks.
+
+To interact with the local task server:
+  • Use the --local flag with other task commands (e.g., 'render tasks list --local')
+  • Or set RENDER_USE_LOCAL_DEV=true when using the workflow client SDK
+
+To use a different port:
+  • Specify --port when starting the dev server
+  • Then use --port with other task commands, or set RENDER_LOCAL_DEV_URL in the SDK
+
+Examples:
+  render ea tasks dev -- "go run main.go"
+  render ea tasks dev --port 9000 -- "npm start"
+  render ea tasks list --local
+  render ea taskruns start my-task --local --input='["arg1"]'
+	`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 
 		ctx := cmd.Context()
@@ -81,11 +104,33 @@ var taskDevCmd = &cobra.Command{
 	Args: cobra.MinimumNArgs(1),
 }
 
-func NewTaskRunCmd(deps flows.WorkflowDeps) *cobra.Command {
+func NewTaskRunStartCmd(deps flows.WorkflowDeps) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "run [taskID]",
-		Short: "Run a new task",
-		Args:  cobra.MaximumNArgs(1),
+		Use:   "start [taskID] --input=<json>",
+		Short: "Start a task run with the provided input",
+		Long: `Start a task with the provided input.
+
+You can specify the task by:
+  • Task ID (e.g., tsk-1234)
+  • Workflow slug and task name (e.g., my-workflow/my-task)
+
+Input Format:
+The input should be a JSON array where each element is an argument to the task.
+For example, if your task takes two arguments, provide: ["arg1", "arg2"]
+
+You can provide input via:
+  • --input with inline JSON
+  • --input-file with a path to a JSON file
+
+In interactive mode, you will be prompted to select the task and provide the input.
+
+Examples:
+  render ea taskruns start tsk-1234 --input='["arg1", "arg2"]'
+  render ea taskruns start my-workflow/my-task --input='[42, "hello"]'
+  render ea taskruns start my-task --input-file=input.json
+  render ea taskruns start my-task --local --input='["test"]'
+`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			deps, local, err := getLocalDeps(cmd, deps)
 			if err != nil {
@@ -124,7 +169,10 @@ func NewTaskRunCmd(deps flows.WorkflowDeps) *cobra.Command {
 		},
 	}
 
-	cmd.Flags().String("input", "", "JSON input to pass to the task")
+	cmd.Flags().String(
+		"input", "",
+		"JSON array input to pass to the task (e.g., '[\"arg1\", \"arg2\"]')",
+	)
 	cmd.Flags().String("input-file", "", "File containing JSON input to pass to the task")
 	cmd.MarkFlagFilename("input-file")
 

cmd/tasklist.go

@@ -15,8 +15,25 @@ import (
 func NewTaskListCmd(deps flows.WorkflowDeps) *cobra.Command {
 	taskListCmd := &cobra.Command{
 		Use:   "list [workflowVersionID]",
-		Short: "List tasks for a workflow version",
-		Args:  cobra.MaximumNArgs(1),
+		Short: "List tasks in a workflow version",
+		Long: `List all tasks defined in a workflow version.
+
+Tasks are user-defined functions registered with the Render workflow SDK. Each time you
+release a workflow service, Render creates a new workflow version and registers all tasks
+it finds in that version.
+
+In interactive mode, you will be prompted to select a workflow version if not provided.
+
+Local Development:
+When using the --local flag, you don't need to provide a workflow version ID. Instead,
+the command connects to your local dev server (default port 8120) to list tasks from
+your running workflow service. Start the dev server with 'render ea tasks dev' first.
+
+Examples:
+  render ea tasks list wfv-1234
+  render ea tasks list --local
+`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			deps, local, err := getLocalDeps(cmd, deps)
 			if err != nil {

cmd/taskrun.go

@@ -0,0 +1,25 @@
+package cmd
+
+import "github.com/spf13/cobra"
+
+var taskRunCmd = &cobra.Command{
+	Use:   "taskruns",
+	Short: "Manage task runs",
+	Long: `Manage task run executions.
+
+A task run represents a single execution of a task with specific input parameters.
+Use these commands to start new task runs, view their history, and inspect details.
+
+Available commands:
+  start    - Execute a task with input parameters
+  list     - List all runs for a task
+  show     - Show detailed information about a specific run
+`,
+}
+
+func init() {
+	taskRunCmd.PersistentFlags().Bool("local", false, "Run against the server spawned by the task dev command")
+	taskRunCmd.PersistentFlags().Int("port", defaultTaskAPIPort, "Port of the local task server (8120 when not specified)")
+
+	EarlyAccessCmd.AddCommand(taskRunCmd)
+}

cmd/taskrundetails.go

@@ -13,8 +13,24 @@ import (
 
 func NewTaskRunDetailsCmd(deps flows.WorkflowDeps) *cobra.Command {
 	return &cobra.Command{
-		Use:   "details [taskRunID]",
-		Short: "Get details for a task run",
+		Use:   "show [taskRunID]",
+		Short: "Show detailed information about a task run",
+		Long: `Display detailed information about a specific task run execution.
+
+This command shows comprehensive information about a task run, including:
+  • Task run ID and status
+  • Input parameters provided
+  • Output or error result
+  • Start and completion timestamps
+
+The task run ID is returned when you execute a task with 'render ea taskruns start'.
+
+In interactive mode, you will be prompted to select a task run if not provided.
+
+Examples:
+  render ea taskruns show tr-1234
+  render ea taskruns show --local tr-5678
+`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			deps, local, err := getLocalDeps(cmd, deps)
 			if err != nil {

cmd/taskrunlist.go

@@ -14,9 +14,25 @@ import (
 
 func NewTaskRunListCmd(deps flows.WorkflowDeps) *cobra.Command {
 	var taskRunListCmd = &cobra.Command{
-		Use:   "runs [taskID]",
+		Use:   "list [taskID]",
 		Short: "List task runs for a task",
-		Args:  cobra.MaximumNArgs(1),
+		Long: `List all execution runs for a specific task.
+
+A task run represents a single execution of a task with specific input parameters.
+This command shows the history of all runs for a given task.
+
+You can specify the task by:
+  • Task ID (e.g., tsk-1234)
+  • Workflow slug and task name (e.g., my-workflow/my-task)
+
+In interactive mode, you will be prompted to select a task if not provided.
+
+Examples:
+  render ea taskruns list tsk-1234
+  render ea taskruns list my-workflow/my-task
+  render ea taskruns list --local my-task
+`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			deps, local, err := getLocalDeps(cmd, deps)
 			if err != nil {

cmd/versionlist.go

@@ -15,8 +15,25 @@ import (
 func NewVersionListCmd(deps flows.WorkflowDeps) *cobra.Command {
 	var versionListCmd = &cobra.Command{
 		Use:   "list [workflowID]",
-		Short: "List versions for a workflow",
-		Args:  cobra.MaximumNArgs(1),
+		Short: "List versions of a workflow",
+		Long: `List all versions of a workflow service.
+
+Each time you release a workflow service, Render creates a new workflow version. A version
+represents a specific snapshot of your workflow service code and its registered tasks at
+the time of release.
+
+This command displays all versions for a workflow, showing:
+  • Version ID
+  • Creation timestamp
+  • Associated tasks
+
+In interactive mode, you will be prompted to select a workflow if not provided.
+
+Examples:
+  render ea versions list wf-1234
+  render ea versions list my-workflow-slug
+`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var input workflowviews.VersionListInput
 			err := command.ParseCommand(cmd, args, &input)

cmd/versionrelease.go

@@ -17,7 +17,33 @@ func NewVersionReleaseCmd(deps flows.WorkflowDeps) *cobra.Command {
 	var versionReleaseCmd = &cobra.Command{
 		Use:   "release [workflowID]",
 		Short: "Release a new workflow version",
-		Args:  cobra.MaximumNArgs(1),
+		Long: `Release a new version of a workflow service.
+
+This command triggers a new release of your workflow service on Render. When you release,
+Render:
+  1. Pulls the latest code from your repository (or a specific commit)
+  2. Builds your workflow service
+  3. Registers all tasks it finds in the service
+  4. Creates a new workflow version
+
+You can optionally specify a commit ID to release a specific version of your code.
+
+Flags:
+  --commit    Specify a commit ID to release (optional)
+  --wait      Wait for the release to complete before returning (optional)
+              Returns a non-zero exit code if the release fails
+
+In interactive mode, you will be prompted to:
+  • Select a workflow if not provided
+  • Confirm the release
+
+Examples:
+  render ea versions release wf-1234
+  render ea versions release my-workflow-slug
+  render ea versions release wf-1234 --commit abc123
+  render ea versions release wf-1234 --wait
+`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var input workflowviews.VersionReleaseInput
 			err := command.ParseCommand(cmd, args, &input)