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 --helpThis 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
--flagwith 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 createScope
Changes would be needed in:
- The CLI argument parser for
model method runto intercept--helpbefore executing the method - A renderer that introspects the method's Zod
argumentsschema to extract field names, types, descriptions, and required/optional/default status - The method's own
descriptionfield 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
Closed
No activity in this phase yet.
Sign in to post a ripple.