Markdown backticks in flag descriptions become garbage metavars (Cobra UnquoteUsage)
- Dominant language
- Go
- Stars
- 1
- Forks
- 0
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 18
Description
## Bug
Generated flag help shows garbage metavar placeholders taken from words inside the description: `--prerequisites true`, `--rules allEnvironments`, `--environments rules`, `--cache preferred`, `--status open`, `--mine author`, etc. The generated docs (`docs/*.md`) have the same.
## Root cause (Speakeasy)
Cobra's `pflag.UnquoteUsage` treats the **first back-quoted word** in a flag's usage string as the metavar placeholder. Spec field descriptions legitimately use markdown backticks (e.g. "must evaluate to `` `true` ``"), and the generated `flagutil.RegisterFlags` passes the description straight to Cobra, so the back-quoted word becomes the metavar.
## Stopgap fix (retire when upstream is fixed)
`.speakeasy/patches/internal/flagutil/metadata.go.patch`: `RegisterFlags` strips backticks from each `Description` before registering the flag → placeholders fall back to the type name (`string`, `stringArray`). Fixes both `--help` and the regenerated docs.
**To retire:** once Speakeasy strips/escapes backticks in descriptions or emits explicit metavars, drop that hunk.
## Refs
- Introduced by #23
- Upstream: file to speakeasy-api/speakeasy (flag registration / Cobra usage strings).
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with .speakeasy/patches/internal/flagutil/metadata.go.patch and inspect RegisterFlags, then compare the generated flag help and docs/*.md examples in the issue. Verify that backticks in descriptions no longer become metavars, that placeholders fall back to type names, and note that the workaround can be retired only when the upstream Speakeasy behavior is fixed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100