Skip to content

CLI gen: default human-readable response formatter with --json toggle #342

Description

@HavenDV

Part of #338.

Today

Every generated command calls CliRuntime.WriteJsonAsync(...) — raw JSON is the only output. Users who want a readable terminal view (let alone scrubbing structured data into a pipeline) have to write custom formatters per response type.

Firecrawl's Commands/ ships FormatScrapeResponse, FormatCrawlStatus, FormatStartResult, etc. — hundreds of lines of hand-written formatting. The pattern is uniform: walk the response, highlight key scalars, render arrays as bullets, render dates with a sensible format.

Target

Default to a generic schema-walking formatter; opt out to raw JSON with --json.

$ firecrawl scrape https://example.com
URL:         https://example.com
Status:      success
Markdown:    # Example Domain ...
Metadata:
  - title:       Example Domain
  - language:    en
  - statusCode:  200
$ firecrawl scrape https://example.com --json
{"url":"...","markdown":"...",...}

Proposed approach

  1. Generate a Format<TResponse>(TResponse value) method per response type that walks the model's PropertyData:
    • scalar → key: value line
    • string > 80 chars → truncate with ellipsis (full text behind --json or --output file.txt)
    • array of scalar → multi-line bullets
    • nested object → indented sub-section
    • array of object → numbered entries with two-level indent
    • dates → yyyy-MM-dd HH:mm:ss UTC
  2. --json recursive option at the root command level (added to existing --api-key/--base-url set) flips output mode. Already half-present: CliRuntime.WriteJsonAsync exists; needs a sibling WriteFormattedAsync.
  3. Vendor extension x-cli-format on a property:
    • key → render at the top of the output
    • hidden → skip from formatted view (still in --json)
    • code → render in a code-block style (preformatted)
  4. Partial-class hook for full override:
    partial class ScrapeCommand
    {
        static partial Task<string> CustomizeFormatAsync(Response response, ParseResult ctx);
    }
  5. Mirror to CliGenerator.cs.

Acceptance criteria

  • Default firecrawl scrape <url> shows human-readable output, --json shows raw JSON.
  • x-cli-format: key on a property promotes it to the top of the output.
  • Partial-class override works without touching the generated .g.cs file.
  • Snapshot tests cover at least: simple scalar response, nested object, array of objects, mixed.

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