Problem
The secrets surface in gapp uses different verb forms across its CLI and its MCP tool interfaces, both of which ship in the same package:
| Surface |
Form |
| CLI |
gapp secrets get, gapp secrets list, gapp secrets set (plural) |
| MCP tools |
gapp_secret_get, gapp_secret_list, gapp_secret_set (singular) |
Both forms are functionally identical. They take the same arguments, hit the same underlying SDK, and return the same data. But an operator (or agent) using one surface and then the other has to mentally remap the noun, and the asymmetry is visible in any documentation that references both — including the secrets/SKILL.md skill that ships with the package, where examples accurately use both forms because both are correct for their respective surface.
This is the kind of papercut that compounds: every doc, every error message, every agent-prompt that mentions a secrets command has to be aware of which surface the reader is on. Easier to fix the surface than to keep both worlds in mind everywhere.
Proposed direction
Pick one form and align both surfaces. Plural is the more common shell convention for resource groups (gcloud secrets, kubectl secrets, docker secrets, aws secretsmanager) and is already what the CLI uses, so the lower-disruption path is:
- Rename the MCP tools to plural:
gapp_secrets_get, gapp_secrets_list, gapp_secrets_set
- Keep the CLI as-is
If singular is preferred for some reason (e.g., MCP convention elsewhere in the package, namespacing concerns), the alternative is to rename the CLI subcommand group to gapp secret <verb> and keep MCP tools singular. Either way, both surfaces should agree.
If renaming is too disruptive in the short term, document the divergence prominently in secrets/SKILL.md and the package README so it stops surprising readers.
Context
Discovered while operating against a deployed solution from an agent session: the agent reached for gapp secret get (singular), got No such command 'secret', and had to switch to gapp secrets get (plural). The same agent in the same session called gapp_secret_get via the MCP tool earlier and it just worked. Trivially recoverable, but the friction is real and avoidable.
Verified against gapp 3.0.7:
$ gapp secret --help
Error: No such command 'secret'.
$ gapp secrets --help
Usage: gapp secrets [OPTIONS] COMMAND [ARGS]...
List, get, and set secret values for the current solution.
Commands:
get Fetch a secret.
list Show declared secrets, deploy-readiness, and remediation hints.
set Store a secret value.
# MCP tool names visible in plugin metadata:
# gapp_secret_get, gapp_secret_list, gapp_secret_set
Work breakdown
Problem
The secrets surface in gapp uses different verb forms across its CLI and its MCP tool interfaces, both of which ship in the same package:
gapp secrets get,gapp secrets list,gapp secrets set(plural)gapp_secret_get,gapp_secret_list,gapp_secret_set(singular)Both forms are functionally identical. They take the same arguments, hit the same underlying SDK, and return the same data. But an operator (or agent) using one surface and then the other has to mentally remap the noun, and the asymmetry is visible in any documentation that references both — including the
secrets/SKILL.mdskill that ships with the package, where examples accurately use both forms because both are correct for their respective surface.This is the kind of papercut that compounds: every doc, every error message, every agent-prompt that mentions a secrets command has to be aware of which surface the reader is on. Easier to fix the surface than to keep both worlds in mind everywhere.
Proposed direction
Pick one form and align both surfaces. Plural is the more common shell convention for resource groups (
gcloud secrets,kubectl secrets,docker secrets,aws secretsmanager) and is already what the CLI uses, so the lower-disruption path is:gapp_secrets_get,gapp_secrets_list,gapp_secrets_setIf singular is preferred for some reason (e.g., MCP convention elsewhere in the package, namespacing concerns), the alternative is to rename the CLI subcommand group to
gapp secret <verb>and keep MCP tools singular. Either way, both surfaces should agree.If renaming is too disruptive in the short term, document the divergence prominently in
secrets/SKILL.mdand the package README so it stops surprising readers.Context
Discovered while operating against a deployed solution from an agent session: the agent reached for
gapp secret get(singular), gotNo such command 'secret', and had to switch togapp secrets get(plural). The same agent in the same session calledgapp_secret_getvia the MCP tool earlier and it just worked. Trivially recoverable, but the friction is real and avoidable.Verified against gapp 3.0.7:
Work breakdown
secrets/SKILL.mdexamples to use the canonical form throughoutCONTRIBUTING.mdabout CLI ↔ MCP tool naming conventions so future surfaces stay aligned