Add markdown output format to CLI list commands (#78)

Furisto · construct-agent · web-flow · commit 20dbe0b3f127 · 2026-01-11T15:02:53.000+01:00
Extend CLI output options with markdown formatting support across all list
commands (agent, task, message, model, provider). Useful for generating
documentation, reports, or copy-pasteable content.

Co-authored-by: construct-agent &lt;noreply@construct.sh&gt;
diff --git a/docs/cli_reference.md b/docs/cli_reference.md
@@ -199,14 +199,17 @@ construct agent list [flags]
   * `-m, --model <model-name|id>`: Filter agents by the model they use.
   * `-n, --name <string>`: Filter agents by name (supports partial matching).
   * `-l, --limit <number>`: Limit the number of results returned.
-  * `--output <table|json|yaml>`: Specify the output format.
+  * `--output <table|json|yaml|markdown>`: Specify the output format. Use `markdown` or `md` for markdown output.
 
 **Examples**
 
 ```bash
 # List all agents in a table
 construct agent list
 
+# Export agents as markdown for documentation
+construct agent list --output markdown
+
 # Find all agents using a specific model
 construct agent ls --model "claude-3-5-sonnet"
 ```
@@ -331,7 +334,7 @@ construct task list [flags]
 
   * `-a, --agent <name|id>`: Filter tasks by the agent assigned to them.
   * `-l, --limit <number>`: Limit the number of results returned.
-  * `--output <table|json|yaml>`: Specify the output format.
+  * `--output <table|json|yaml|markdown>`: Specify the output format. Use `markdown` or `md` for markdown output.
 
 **Examples**
 
@@ -438,7 +441,7 @@ Lists messages, typically filtered by a specific task. Useful for reviewing or e
   * `-t, --task <task-id>`: (Recommended) Filter messages by task ID.
   * `-a, --agent <name|id>`: Filter by the agent that participated in the conversation.
   * `-r, --role <user|assistant>`: Filter messages by the role of the author.
-  * `--output <table|json|yaml>`: Specify the output format.
+  * `--output <table|json|yaml|markdown>`: Specify the output format. 
 
 **Examples**
 
@@ -501,7 +504,7 @@ construct model list [flags]
 **Options**
 
   * `-p, --provider <name|id>`: Filter models by their provider.
-  * `--output <table|json|yaml>`: Specify the output format.
+  * `--output <table|json|yaml|markdown>`: Specify the output format.
 
 **Examples**
 
@@ -565,7 +568,7 @@ construct provider list [flags]
 **Options**
 
   * `-t, --type <openai|anthropic>`: Filter providers by type.
-  * `--output <table|json|yaml>`: Specify the output format.
+  * `--output <table|json|yaml|markdown>`: Specify the output format.
 
 **Examples**
 
diff --git a/frontend/cli/cmd/print.go b/frontend/cli/cmd/print.go
@@ -23,10 +23,11 @@ type RenderOptions struct {
 type OutputFormat string
 
 const (
-	OutputFormatJSON  OutputFormat = "json"
-	OutputFormatYAML  OutputFormat = "yaml"
-	OutputFormatTable OutputFormat = "table"
-	OutputFormatCard  OutputFormat = "card"
+	OutputFormatJSON     OutputFormat = "json"
+	OutputFormatYAML     OutputFormat = "yaml"
+	OutputFormatTable    OutputFormat = "table"
+	OutputFormatCard     OutputFormat = "card"
+	OutputFormatMarkdown OutputFormat = "markdown"
 )
 
 func (e *OutputFormat) String() string {
@@ -37,12 +38,15 @@ func (e *OutputFormat) String() string {
 }
 
 func (e *OutputFormat) Set(v string) error {
+	if v == "md" {
+		v = "markdown"
+	}
 	switch v {
-	case "json", "yaml", "table", "card":
+	case "json", "yaml", "table", "card", "markdown":
 		*e = OutputFormat(v)
 		return nil
 	default:
-		return errors.New(`must be one of "json" or "yaml"`)
+		return errors.New(`must be one of "json", "yaml", "table", "card", or "markdown"`)
 	}
 }
 
@@ -64,7 +68,7 @@ func addRenderOptions(cmd *cobra.Command, options *RenderOptions) {
 		WithTableFormat(options)
 	}
 
-	cmd.Flags().VarP(&options.Format, "output", "o", fmt.Sprintf("output format (json, yaml, table, card)(default: %s)", options.Format))
+	cmd.Flags().VarP(&options.Format, "output", "o", fmt.Sprintf("output format (json, yaml, table, card, markdown) (default: %s)", options.Format))
 	cmd.Flags().BoolVarP(&options.Wide, "wide", "w", false, "output verbosity (default: false)")
 	cmd.Flags().BoolVarP(&options.NoHeaders, "no-headers", "", false, "do not print headers (default: false)")
 }
@@ -102,6 +106,11 @@ func (f *DefaultRenderer) Render(resources any, options *RenderOptions) (err err
 		if err != nil {
 			return err
 		}
+	case OutputFormatMarkdown:
+		err = renderMarkdown(resources, options)
+		if err != nil {
+			return err
+		}
 	default:
 		return fmt.Errorf("unsupported output format: %s", options.Format)
 	}
@@ -334,6 +343,128 @@ func renderCard(resources any, options *RenderOptions) error {
 	return nil
 }
 
+func renderMarkdown(resources any, options *RenderOptions) error {
+	if resources == nil {
+		return nil
+	}
+
+	value := reflect.ValueOf(resources)
+	typ := reflect.TypeOf(resources)
+
+	if value.Kind() == reflect.Ptr {
+		if value.IsNil() {
+			return nil
+		}
+		value = value.Elem()
+		typ = typ.Elem()
+	}
+
+	var items []reflect.Value
+	var itemType reflect.Type
+
+	if value.Kind() == reflect.Slice {
+		if value.Len() == 0 {
+			return nil
+		}
+		for i := 0; i < value.Len(); i++ {
+			items = append(items, value.Index(i))
+		}
+		itemType = typ.Elem()
+	} else {
+		items = append(items, value)
+		itemType = typ
+	}
+
+	if itemType.Kind() == reflect.Ptr {
+		itemType = itemType.Elem()
+	}
+
+	if itemType.Kind() != reflect.Struct {
+		return fmt.Errorf("renderMarkdown only supports struct types, got %v", itemType.Kind())
+	}
+
+	var fields []reflect.StructField
+	for i := 0; i < itemType.NumField(); i++ {
+		field := itemType.Field(i)
+		if includeField(field, options.Wide) {
+			fields = append(fields, field)
+		}
+	}
+
+	if len(fields) == 0 {
+		return nil
+	}
+
+	for idx, item := range items {
+		if item.Kind() == reflect.Ptr {
+			if item.IsNil() {
+				continue
+			}
+			item = item.Elem()
+		}
+
+		for _, field := range fields {
+			fieldValue := item.FieldByName(field.Name)
+			if !fieldValue.IsValid() {
+				continue
+			}
+
+			valueStr := formatMarkdownValue(fieldValue)
+			fmt.Printf("**%s:** %s\n", field.Name, valueStr)
+		}
+
+		if idx < len(items)-1 {
+			fmt.Print("\n---\n\n")
+		}
+	}
+
+	return nil
+}
+
+func formatMarkdownValue(v reflect.Value) string {
+	if !v.IsValid() {
+		return ""
+	}
+
+	switch v.Kind() {
+	case reflect.Ptr:
+		if v.IsNil() {
+			return ""
+		}
+		return formatMarkdownValue(v.Elem())
+	case reflect.String:
+		return v.String()
+	case reflect.Slice:
+		if v.Len() == 0 {
+			return ""
+		}
+		var parts []string
+		for i := 0; i < v.Len(); i++ {
+			parts = append(parts, formatMarkdownValue(v.Index(i)))
+		}
+		return strings.Join(parts, ", ")
+	case reflect.Map:
+		if v.Len() == 0 {
+			return ""
+		}
+		var parts []string
+		iter := v.MapRange()
+		for iter.Next() {
+			k := fmt.Sprint(iter.Key().Interface())
+			val := formatMarkdownValue(iter.Value())
+			parts = append(parts, fmt.Sprintf("%s=%s", k, val))
+		}
+		return strings.Join(parts, ", ")
+	case reflect.Struct:
+		if v.Type().String() == "time.Time" {
+			return fmt.Sprint(v.Interface())
+		}
+		return fmt.Sprint(v.Interface())
+	default:
+		return fmt.Sprint(v.Interface())
+	}
+}
+
 func includeField(field reflect.StructField, wide bool) bool {
 	return field.IsExported() && (field.Tag.Get("detail") == "default" || (wide && field.Tag.Get("detail") == "full"))
 }
diff --git a/frontend/cli/cmd/print_markdown_test.go b/frontend/cli/cmd/print_markdown_test.go
@@ -0,0 +1,119 @@
+package cmd
+
+import (
+	"bytes"
+	"io"
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestRenderMarkdown(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    any
+		options  *RenderOptions
+		expected []string
+	}{
+		{
+			name: "single struct",
+			input: &AgentDisplay{
+				ID:          "123",
+				Name:        "test-agent",
+				Description: "A test agent",
+				Model:       "gpt-4",
+			},
+			options: &RenderOptions{Format: OutputFormatMarkdown},
+			expected: []string{
+				"**ID:** 123",
+				"**Name:** test-agent",
+				"**Description:** A test agent",
+				"**Model:** gpt-4",
+			},
+		},
+		{
+			name: "slice of structs",
+			input: []*AgentDisplay{
+				{ID: "1", Name: "agent-one", Model: "gpt-4"},
+				{ID: "2", Name: "agent-two", Model: "claude"},
+			},
+			options: &RenderOptions{Format: OutputFormatMarkdown},
+			expected: []string{
+				"**ID:** 1",
+				"**Name:** agent-one",
+				"---",
+				"**ID:** 2",
+				"**Name:** agent-two",
+			},
+		},
+		{
+			name:     "nil input",
+			input:    nil,
+			options:  &RenderOptions{Format: OutputFormatMarkdown},
+			expected: []string{},
+		},
+		{
+			name:     "empty slice",
+			input:    []*AgentDisplay{},
+			options:  &RenderOptions{Format: OutputFormatMarkdown},
+			expected: []string{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Capture stdout
+			old := os.Stdout
+			r, w, _ := os.Pipe()
+			os.Stdout = w
+
+			err := renderMarkdown(tt.input, tt.options)
+			if err != nil {
+				t.Fatalf("renderMarkdown() error = %v", err)
+			}
+
+			w.Close()
+			var buf bytes.Buffer
+			io.Copy(&buf, r)
+			os.Stdout = old
+
+			output := buf.String()
+
+			for _, exp := range tt.expected {
+				if !strings.Contains(output, exp) {
+					t.Errorf("expected output to contain %q, got:\n%s", exp, output)
+				}
+			}
+		})
+	}
+}
+
+func TestOutputFormatSet(t *testing.T) {
+	tests := []struct {
+		input    string
+		expected OutputFormat
+		wantErr  bool
+	}{
+		{"json", OutputFormatJSON, false},
+		{"yaml", OutputFormatYAML, false},
+		{"table", OutputFormatTable, false},
+		{"card", OutputFormatCard, false},
+		{"markdown", OutputFormatMarkdown, false},
+		{"md", OutputFormatMarkdown, false},
+		{"invalid", "", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			var f OutputFormat
+			err := f.Set(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("OutputFormat.Set(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr)
+				return
+			}
+			if !tt.wantErr && f != tt.expected {
+				t.Errorf("OutputFormat.Set(%q) = %v, want %v", tt.input, f, tt.expected)
+			}
+		})
+	}
+}
