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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions