Surface useful, actionable errors in the CLI using `dry/usefulerror`
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 4
- Forks
- 0
- Avg merge
- 5h 55m
- Merged PRs (30d)
- 9
Description
Problem
CLI errors are often raw gRPC/internal messages that don't help users (or agents) understand what went wrong or how to fix it. Example from query exec:
Error: cloudquery: query: rpc error: code = Internal desc = server closed the stream without sending trailers
This tells the user nothing actionable.
Proposal
Adopt usefulerror from safedep/dry across the CLI so errors carry a human message, help text, and a reference URL instead of leaking transport-level detail.
dry/usefulerror already ships gRPC converters for the standard codes, so most of the mapping comes for free — we render its fields at the CLI's top-level error boundary and add CLI-specific mappings only where the generic message isn't enough.
Docs
Add a troubleshooting page on docs.safedep.io keyed by error code, and link each error's reference URL to the relevant entry. Beyond helping users, this is especially useful for coding agents: when a command fails, an agent can look up the error code and apply the documented fix on its own, instead of the user having to stop, debug, or hunt for a workaround.
Outcome
Errors become self-explanatory and greppable by code, with a doc link for deeper guidance.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the query exec error path and the CLI's top-level error boundary, then review how dry/usefulerror maps standard gRPC codes. Add CLI-specific mappings where needed, render human messages, help text, and reference URLs, and add a docs.safedep.io troubleshooting page keyed by error code with linked guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, grpc
- Domain
- cli, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100