Parameters and handler input
Declare command parameters and infer their handler input types.
Parameter object keys become handler input keys. The generated manifest uses their kebab-case form: appId becomes app-id, while the handler receives input.appId.
Every param.* builder takes constraint text first. Parameters are optional unless required: true is supplied. repeatable: true makes a string, integer, enum, or positional parameter an array. It cannot be used with boolean, path, or file parameters. A parameter with default remains optional in handler input because crtr applies that default while parsing its command line; the server does not apply it.
| Builder | Handler value | Options |
|---|---|---|
param.string(constraint, options?) | string | required, repeatable, default |
param.int(constraint, options?) | number | required, repeatable, default |
param.bool(constraint, options?) | boolean | required, default |
param.enum(choices, constraint, options?) | a member of choices | required, repeatable, default |
param.path(constraint, options?) | string for encoding: 'text', Uint8Array for encoding: 'base64' | required, encoding |
param.file(constraint, options?) (same as field.file) | string | required |
param.positional(constraint, options?) | string | required, repeatable |
param.stdin(constraint, options?) | string | required |
param.positional is the one positional argument a leaf may have. param.stdin receives the command's standard input. param.path receives the contents of the local file named by the crtr caller, never the path string. Text is UTF-8. Base64 mode decodes the caller's file bytes into a Uint8Array before the handler runs.
param.file declares a file parameter. The agent passes a runtime path. When a capability provider is called, the runtime uploads a copy and the handler receives a signed https download link as a string, valid for 15 minutes. The file's name is the link's last path segment. With a local --endpoint install, the handler receives the string the agent typed. Unlike param.path, the handler never receives the file contents inline. param.file and field.file return the same descriptor, so either works in params.
The handler input is inferred from the parameter object with no manual annotation. In the package README sample, input is inferred as { name: string; region?: 'us-east' | 'eu-west' }. A required parameter is present, optional parameters can be absent, enum choices remain literal values, and repeatable parameters are arrays.
definePlugin checks parameter descriptor objects when the module loads. A malformed hand-built descriptor throws PluginDefinitionError at that call. Use the builders instead of constructing descriptor objects.