Labsco
github logo

console-rendering

✓ Official★ 4,700

by github · part of github/gh-aw

Instructions for using the struct tag-based console rendering system in Go

🔥🔥✓ VerifiedFreeQuick setup
#git
🔒 Repo-maintenance skill. It exists to help maintain github/gh-aw itself — it's only useful if you contribute code to that project.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

name: console-rendering description: Use Go struct tags to render styled terminal output in gh-aw.

Console Rendering System Usage

Use this guide for the struct tag-based console rendering system.

Struct Tag Support

Use the console struct tag to control rendering behavior:

  • header:"Name" - Sets the display name for fields (used in both structs and tables)
  • title:"Section Title" - Sets the title for nested structs, slices, or maps
  • format:"type" - Sets the formatting type for the field value
    • format:number - Formats integers as human-readable numbers (e.g., "1k", "1.2M")
    • format:cost - Formats floats as currency with $ prefix (e.g., "$1.234")
  • omitempty - Skips the field if it has a zero value
  • "-" - Always skips the field

Format Tag Examples

Number Formatting

type Metrics struct {
    TokenUsage int `console:"header:Token Usage,format:number"`
    Errors     int `console:"header:Errors"`
}

data := Metrics{
    TokenUsage: 250000,
    Errors:     5,
}

// Renders as:
//   Token Usage: 250k
//   Errors     : 5

Cost Formatting

type Billing struct {
    Cost float64 `console:"header:Estimated Cost,format:cost"`
}

data := Billing{
    Cost: 1.234,
}

// Renders as:
//   Estimated Cost: $1.234

Rendering Behavior

Structs

Structs are rendered as key-value pairs with proper alignment.

Slices

Slices of structs are automatically rendered as tables:

type Job struct {
    Name       string `console:"header:Name"`
    Status     string `console:"header:Status"`
    Conclusion string `console:"header:Conclusion,omitempty"`
}

jobs := []Job{
    {Name: "build", Status: "completed", Conclusion: "success"},
    {Name: "test", Status: "in_progress", Conclusion: ""},
}

fmt.Print(console.RenderStruct(jobs))

Renders as:

Name  | Status      | Conclusion
----- | ----------- | ----------
build | completed   | success
test  | in_progress | -

Maps

Maps are rendered as markdown-style headers with key-value pairs.

Special Type Handling

time.Time

time.Time fields are automatically formatted as "2006-01-02 15:04:05". Zero time values are considered empty when used with omitempty.

Unexported Fields

The rendering system safely handles unexported struct fields by checking CanInterface() before attempting to access field values.