Skip to main content
← Back to list
01Issue
FeatureClosedSwamp Club
AssigneesNone

Support --help flag on custom extension model methods

Opened by swampadmin · 2/13/2025

Problem

When running a custom extension model method with --help, swamp does not display any help content. For example:

swamp model method run honeycomb get --help

This produces no useful output, even though the method definition includes description fields on both the method itself and its Zod argument schemas (via .describe()).

An agent (human or AI) working with swamp models has no way to discover what arguments a method accepts without reading the source code directly.

Proposed Solution

swamp should generate --help output for custom extension model methods using metadata already present in the model definition:

  • Method description → shown as the command summary
  • Zod argument schema → each field becomes a documented --flag with its .describe() text, type, and whether it's required/optional/has a default

Example desired output:

swamp model method run honeycomb get

List all resources of a given type

Arguments:
  --resource  string (required)  Honeycomb resource type (e.g. environments, datasets)

For methods with optional/default arguments:

swamp model method run honeycomb create

Create a new resource of a given type

Arguments:
  --resource  string (required)  Honeycomb resource type (e.g. environments, datasets)
  --name      string (required)  Name of the resource to create

Scope

Changes would be needed in:

  • The CLI argument parser for model method run to intercept --help before executing the method
  • A renderer that introspects the method's Zod arguments schema to extract field names, types, descriptions, and required/optional/default status
  • The method's own description field should be displayed as the top-level summary

All the metadata needed is already defined in extension models — this is purely about surfacing it in the CLI.

Alternatives Considered

  • External documentation: Users could maintain separate docs, but this duplicates information already in the schema and goes stale
  • swamp model type describe: This shows the full model schema but doesn't focus on a specific method's arguments in a CLI-friendly format
02Bog Flow
OPENTRIAGEDIN PROGRESSCLOSED

Closed

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.