Skip to content

feat(awn): add toon format output support #164

@Jing-yilin

Description

@Jing-yilin

Summary

Add support for toon format output in awn CLI commands alongside existing JSON and human-readable text formats.

Motivation

Toon is a structured format designed for AI-to-human communication in terminals. Adding toon format support will:

  • Enable better AI agent integration with human-readable structured output
  • Provide rich formatting capabilities (colors, tables, code blocks, etc.)
  • Improve CLI UX for both human and AI users
  • Standardize output format across AI tools

Proposed Solution

Add --toon flag

awn --toon status
awn --toon worlds
awn --toon world <world_id>
awn --toon agents

Output format examples

Status command:

# AWN Status

Agent ID: aw:sha256:abc123...
Version: v1.4.0
Listen port: 8099
Gateway: https://gateway.agentworlds.ai
Known agents: 5
Data dir: /Users/user/.awn

Worlds command:

# Available Worlds (3)

| World ID | Name | Status | Last Seen |
|----------|------|--------|-----------|
| world:pixel-city | Pixel City | reachable | 5s ago |
| world:dungeon | Dungeon World | no endpoint | 120s ago |
| world:test | Test World | reachable | 10s ago |

World info command:

# World Info: Pixel City

**World ID:** aw:sha256:abc123...
**Status:** reachable

## Endpoints
- tcp://192.168.1.100:8099 (priority: 0)

## Manifest
**Name:** Pixel City
**Description:** A world on a 32x32 grid.
**Theme:** city

### Actions

#### move
Move to position (x, y) on the grid.

**Parameters:**
- `x` (number, required): Target x position
- `y` (number, required): Target y position

Implementation Plan

  1. Add toon dependency to Cargo.toml
  2. Add --toon flag to CLI (mutually exclusive with --json)
  3. Implement toon formatters for each command response type:
    • StatusResponse
    • AgentsResponse
    • WorldsResponse
    • WorldInfoResponse
  4. Update SKILL.md documentation

Related

Benefits

  • Better AI-to-human communication
  • Consistent structured output format
  • Rich formatting with colors and tables
  • Easier parsing for downstream tools
  • Enhanced terminal UX

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions