logbrew_cli/
help.rs

1//! CLI help text kept separate from command parsing.
2
3use crate::HelpTopic;
4
5/// Returns user-facing help for a topic.
6#[must_use]
7pub const fn help_text(topic: HelpTopic) -> &'static str {
8    match topic {
9        HelpTopic::Root => ROOT_HELP,
10        HelpTopic::Login => LOGIN_HELP,
11        HelpTopic::Logout => LOGOUT_HELP,
12        HelpTopic::Setup => SETUP_HELP,
13        HelpTopic::Status => STATUS_HELP,
14        HelpTopic::Version => VERSION_HELP,
15        HelpTopic::Auth => AUTH_HELP,
16        HelpTopic::Json => JSON_HELP,
17        HelpTopic::Examples => EXAMPLES_HELP,
18        HelpTopic::Projects => PROJECTS_HELP,
19        HelpTopic::Usage => USAGE_HELP,
20        HelpTopic::Read => READ_HELP,
21        HelpTopic::ReadLogs => READ_LOGS_HELP,
22        HelpTopic::ReadIssues => READ_ISSUES_HELP,
23        HelpTopic::ReadActions => READ_ACTIONS_HELP,
24        HelpTopic::ReadReleases => READ_RELEASES_HELP,
25        HelpTopic::ReadTrace => READ_TRACE_HELP,
26        HelpTopic::ReadIssue => READ_ISSUE_HELP,
27        HelpTopic::Watch => WATCH_HELP,
28        HelpTopic::Explain => EXPLAIN_HELP,
29        HelpTopic::Set => SET_HELP,
30    }
31}
32
33/// Root command help text.
34const ROOT_HELP: &str = "\
35LogBrew CLI
36
37Usage:
38  logbrew login [--no-open] [--json]
39  logbrew logout [--json]
40  logbrew setup [--auto] [--yes] [--json]
41  logbrew projects [--json]
42  logbrew usage [--json]
43  logbrew status [--json]
44  logbrew health [--json]
45  logbrew doctor [--json]
46  logbrew whoami [--json]
47  logbrew me [--json]
48  logbrew version [--json]
49  logbrew read logs [--severity error] [--search checkout] [--release <release>] [--environment \
50                         production] [--since 24h] [--json]
51  logbrew logs checkout failed [--severity error] [--release <release>] [--environment \
52                         production] [--json]
53  logbrew logs error checkout failed [--release <release>] [--environment production] [--json]
54  logbrew search checkout [--release <release>] [--environment production] [--json]
55  logbrew find checkout [--release <release>] [--environment production] [--json]
56  logbrew grep checkout [--release <release>] [--environment production] [--json]
57  logbrew show logs [--release <release>] [--environment production] [--json]
58  logbrew latest logs [--limit 20] [--json]
59  logbrew last 10 logs [--json]
60  logbrew last 5 open issues [--json]
61  logbrew list issues [--status unresolved] [--json]
62  logbrew issues open [--release <release>] [--environment production] [--json]
63  logbrew issue open [--release <release>] [--environment production] [--json]
64  logbrew open issues [--release <release>] [--environment production] [--json]
65  logbrew open issue [--release <release>] [--environment production] [--json]
66  logbrew errors closed [--release <release>] [--environment production] [--json]
67  logbrew get issue <issue_id> [--json]
68  logbrew read issues [--release <release>] [--environment production] [--status unresolved] \
69                         [--json]
70  logbrew read actions [--release <release>] [--environment production] [--name checkout_failed] \
71                         [--json]
72  logbrew events checkout_failed [--release <release>] [--environment production] [--json]
73  logbrew read releases [--environment production] [--json]
74  logbrew read trace <trace_id> [--release <release>] [--environment production] [--json]
75  logbrew trace <trace_id> [--release <release>] [--environment production] [--json]
76  logbrew issue <issue_id> [--json]
77  logbrew issue <issue_id> explain [--json]
78  logbrew trace <trace_id> explain [--json]
79  logbrew explain issue <issue_id> [--json]
80  logbrew explain trace <trace_id> [--json]
81  logbrew explain <issue_id_or_trace_id> [--json]
82  logbrew <issue_id_or_trace_id> explain [--json]
83  logbrew set issue <issue_id> resolved [--json]
84  logbrew resolve <issue_id> [--json]
85  logbrew close <issue_id> [--json]
86  logbrew ignore <issue_id> [--json]
87  logbrew reopen <issue_id> [--json]
88
89Popular terms: auth, status, health, setup, projects, usage, logs, issues, errors, traces, spans, \
90                         actions, events, releases, environments.
91Health aliases: logbrew status, logbrew health, logbrew ping, logbrew doctor.
92Setup aliases (non-mutating plan): logbrew init, logbrew install, logbrew configure, logbrew sdk.
93Shortcuts: logbrew auth, logbrew whoami, logbrew me, logbrew log, logbrew logs, logbrew issues, \
94                         logbrew logs checkout failed, logbrew logs error checkout, logbrew \
95                         search checkout, logbrew find checkout, logbrew grep checkout, logbrew \
96                         errors, logbrew actions, logbrew events, logbrew events checkout_failed, \
97                         logbrew release, logbrew releases, logbrew trace <id>, logbrew issue \
98                         <id>, logbrew resolve <id>, logbrew close <id>, logbrew ignore <id>, \
99                         logbrew reopen <id>.
100Read verbs: logbrew show logs, logbrew latest logs, logbrew last 10 logs, logbrew recent issues, \
101                         logbrew list issues, logbrew get issue <id>.
102Singular read aliases: logbrew read log, read release, show log, list issue, get release.
103Pasted IDs: logbrew issue_123 or logbrew <trace_id>.
104Examples: logbrew examples.
105Topic help: logbrew logs --help, logbrew help logs, logbrew help read logs, or logbrew help json.
106JSON mode: logbrew --json status and logbrew status --json both work.
107Use --json for stable machine-readable output.";
108
109/// Login command help text.
110const LOGIN_HELP: &str = "\
111Usage:
112  logbrew login [--no-open] [--json]
113
114Starts browser login for the native CLI. Use --no-open to print the URL without opening a browser.
115--json prints the auth handoff without opening a browser.";
116
117/// Logout command help text.
118const LOGOUT_HELP: &str = "\
119Usage:
120  logbrew logout [--json]
121
122Removes the local CLI token. If LOGBREW_TOKEN is set, unset it to fully log out.";
123
124/// Setup command help text.
125const SETUP_HELP: &str = "\
126Usage:
127  logbrew setup [--auto] [--yes] [--json]
128
129Detects supported project manifests and prints a non-mutating SDK setup plan.
130No files are changed. Install: not ready.
131Aliases (same non-mutating plan): logbrew init, logbrew install, logbrew configure, logbrew sdk.
132Options: --auto records automatic detection preference; --yes records confirmation preference; \
133                          --json prints stable setup JSON.
134Supported manifests: package.json, pyproject.toml, Pipfile, Cargo.toml, Package.swift, \
135                          project.yml, project.yaml, .xcodeproj, .xcworkspace, go.mod, \
136                          composer.json.
137Package managers: npm, pnpm, yarn, bun, pip, uv, poetry, pipenv, cargo, SwiftPM, XcodeGen, Go, \
138                          Composer.";
139
140/// Status command help text.
141const STATUS_HELP: &str = "\
142Usage:
143  logbrew status [--json]
144  logbrew health [--json]
145  logbrew ping [--json]
146  logbrew doctor [--json]
147  logbrew whoami [--json]
148  logbrew me [--json]
149  logbrew auth status [--json]
150
151Checks local auth and API reachability.
152Identity aliases: logbrew whoami, logbrew me, logbrew auth status.";
153
154/// Version command help text.
155const VERSION_HELP: &str = "\
156Usage:
157  logbrew version [--json]
158  logbrew --version [--json]
159
160Prints the installed CLI version.
161The CLI is a native Rust binary.";
162
163/// Auth workflow help text.
164const AUTH_HELP: &str = "\
165Usage:
166  logbrew login [--no-open] [--json]
167  logbrew auth login [--no-open] [--json]
168  logbrew status [--json]
169  logbrew auth status [--json]
170  logbrew auth whoami [--json]
171  logbrew auth me [--json]
172  logbrew whoami [--json]
173  logbrew me [--json]
174  logbrew logout [--json]
175  logbrew auth logout [--json]
176
177Use login once, status/whoami/me to verify API/auth state, and logout to remove the local token.
178Use --json for agent-readable auth checks.";
179
180/// JSON output help text.
181const JSON_HELP: &str = "\
182Usage:
183  logbrew --json status
184  logbrew status --json
185  logbrew logs --json
186  logbrew help json --json
187
188Use --json before or after commands for stable machine-readable output.
189Stable JSON keeps server response shapes for reads and mutations.
190Errors include ok, error, message, and next.";
191
192/// First-run examples and common workflows.
193const EXAMPLES_HELP: &str = "\
194Usage:
195  logbrew examples
196  logbrew help examples
197
198First run:
199  logbrew status
200  logbrew login
201  logbrew setup
202
203Troubleshoot:
204  logbrew logs error checkout failed --release checkout@1 --environment production
205  logbrew issues open --release checkout@1 --environment production
206  logbrew issue issue_123
207  logbrew explain issue issue_123
208  logbrew trace <trace_id>
209
210Live:
211  logbrew watch --json
212  logbrew watch --severity error,critical --json
213
214Agent JSON:
215  logbrew --json status
216  logbrew logs checkout failed --json
217  logbrew explain trace <trace_id> --json
218
219More help:
220  logbrew help logs
221  logbrew help issues
222  logbrew help watch
223  logbrew help json";
224
225/// Backend-owned project setup help text.
226const PROJECTS_HELP: &str = "\
227Usage:
228  logbrew projects [--json]
229  logbrew project [--json]
230  logbrew projects create <name> [--json]
231  logbrew setup --create-project [--json]
232  logbrew projects setup <project_id> [--json]
233
234Project creation, setup status, and project-scoped ingest credentials are backend-owned.
235Current mode: help only. No local project, install, quota, or usage state is created.
236When backend project setup is available, the CLI will call the backend contract and print \
237backend-generated project-scoped SDK/ingest credentials.
238Never use an account bearer token as SDK or ingest configuration.
239Next: run logbrew setup for the current non-mutating local plan.";
240
241/// Backend-owned usage and quota help text.
242const USAGE_HELP: &str = "\
243Usage:
244  logbrew usage [--json]
245  logbrew account usage [--json]
246
247Account usage, plan limits, quota state, reset dates, and per-project or per-stream breakdowns are \
248backend-owned.
249Current mode: help only. The CLI does not calculate or persist usage/quota state from local files.
250When backend usage is available, the CLI will read the backend account usage contract and preserve \
251stable JSON for agents.
252Next: run logbrew status to verify API and auth state.";
253
254/// Read command help text.
255const READ_HELP: &str = "\
256Usage:
257  logbrew read logs [filters] [--json]
258  logbrew read log [filters] [--json]
259  logbrew show logs [filters] [--json]
260  logbrew list issues [filters] [--json]
261  logbrew get issue <issue_id> [--json]
262  logbrew read issues [filters] [--json]
263  logbrew read actions [filters] [--json]
264  logbrew read releases [filters] [--json]
265  logbrew read release [filters] [--json]
266  logbrew read trace <trace_id> [--json]
267  logbrew read issue <issue_id> [--json]
268
269Reads historical observability data for agents and developers.
270Singular read aliases: logbrew read log, read release, show log, list issue, get release.
271Recency counts are limit shortcuts: logbrew last 10 logs or logbrew recent 5 issues.
272Use --environment <environment> with logs, issues, actions, releases, or traces.
273Filter aliases: --env, --project-id, --trace-id, and --distinct-id.";
274
275/// Read logs help text.
276const READ_LOGS_HELP: &str = "\
277Usage:
278  logbrew read logs [--severity error] [--search checkout] [--release <release>] [--environment \
279                              production] [--since 24h] [--trace <trace_id>] [--project \
280                              <project_id>] [--limit 100] [--json]
281  logbrew logs checkout failed [--severity error] [--release <release>] [--environment \
282                              production] [--json]
283  logbrew logs error checkout failed [--release <release>] [--environment production] [--json]
284
285Reads structured logs. Severity values are info, warning, error, and critical.
286Legacy severity aliases are accepted on input and normalized.
287Severity matching is case-insensitive. --level is accepted as a compatibility alias for \
288                              --severity.
289The logs shortcut accepts obvious multi-word search text, such as logbrew logs checkout failed.
290Shortcut levels can include search text, such as logbrew logs error checkout failed.
291Recency counts are limit shortcuts, such as logbrew last 10 logs.
292Explicit filters accept unquoted search text too, such as logbrew logs --severity warning checkout \
293                              failed or logbrew logs --search checkout failed.
294Use -- before literal flag-looking search text, such as logbrew logs -- --timeout --json.
295Filter by severity, message search, release, or trace_id to correlate logs with spans.
296Limit must be a positive whole number.";
297
298/// Read issues help text.
299const READ_ISSUES_HELP: &str = "\
300Usage:
301  logbrew read issues [--release <release>] [--environment production] [--status unresolved] \
302                                [--project <project_id>] [--limit 100] [--json]
303  logbrew issues open [--release <release>] [--environment production] [--json]
304  logbrew issue open [--release <release>] [--environment production] [--json]
305  logbrew open issues [--release <release>] [--environment production] [--json]
306  logbrew open issue [--release <release>] [--environment production] [--json]
307  logbrew last 5 open issues [--json]
308  logbrew errors closed [--release <release>] [--environment production] [--json]
309
310Reads grouped issues across releases and environments.
311Status accepts unresolved/open, resolved/closed, or ignored, case-insensitively.
312Issue shortcuts accept status words, such as logbrew issues open, logbrew issue open, logbrew open \
313                                issues, logbrew open issue, or logbrew errors closed.
314Recency issue shortcuts can include status and count, such as logbrew last 5 open issues.
315Limit must be a positive whole number.";
316
317/// Read actions help text.
318const READ_ACTIONS_HELP: &str = "\
319Usage:
320  logbrew read actions [--release <release>] [--environment production] [--name checkout_failed] \
321                                 [--user <distinct_id>] [--since 24h] [--project <project_id>] \
322                                 [--limit 100] [--json]
323  logbrew events checkout_failed [--release <release>] [--environment production] [--json]
324
325Reads product actions. Use distinct_id to follow one actor or session.
326Action/event aliases accept one positional name as the same filter as --name.
327Limit must be a positive whole number.";
328
329/// Read releases help text.
330const READ_RELEASES_HELP: &str = "\
331Usage:
332  logbrew read releases [--release <release>] [--environment production] [--project <project_id>] \
333                                  [--limit 100] [--json]
334
335Reads release summaries with counts for issues, logs, trace spans, and actions.
336Limit must be a positive whole number.";
337
338/// Read trace help text.
339const READ_TRACE_HELP: &str = "\
340Usage:
341  logbrew read trace <trace_id> [--release <release>] [--environment production] [--project \
342                               <project_id>] [--json]
343
344Reads spans for one distributed trace.";
345
346/// Read issue help text.
347const READ_ISSUE_HELP: &str = "\
348Usage:
349  logbrew read issue <issue_id> [--json]
350
351Reads one grouped issue with status, release, environment, and occurrence counts.";
352
353/// Watch command help text.
354const WATCH_HELP: &str = "\
355Usage:
356  logbrew watch --json
357  logbrew watch logs [--json]
358  logbrew watch issues [--json]
359  logbrew watch actions [--json]
360  logbrew watch --severity error,critical --json
361
362Aliases: tail, follow, and stream use the same live watch flow.
363Live watch uses a short-lived feed ticket and WebSocket stream.
364Transient disconnects reconnect with a fresh ticket and backoff.
365Server-side live filters are not sent yet; severity filtering is applied client-side.";
366
367/// Explain command help text.
368const EXPLAIN_HELP: &str = "\
369Usage:
370  logbrew explain issue <issue_id> [--json]
371  logbrew explain trace <trace_id> [--json]
372  logbrew explain <issue_id_or_trace_id> [--json]
373  logbrew issue <issue_id> explain [--json]
374  logbrew trace <trace_id> explain [--json]
375  logbrew <issue_id_or_trace_id> explain [--json]
376
377Fetches enough context for an AI agent to explain what happened.
378Pasted UUID/issue_* values are treated as issues; 32-hex/trace_* values are treated as traces.";
379
380/// Set command help text.
381const SET_HELP: &str = "\
382Usage:
383  logbrew set issue <issue_id> unresolved [--json]
384  logbrew set issue <issue_id> resolved [--json]
385  logbrew set issue <issue_id> ignored [--json]
386  logbrew resolve <issue_id> [--json]
387  logbrew close <issue_id> [--json]
388  logbrew ignore <issue_id> [--json]
389  logbrew reopen <issue_id> [--json]
390  logbrew issue <issue_id> resolve [--json]
391  logbrew issue <issue_id> close [--json]
392  logbrew issue <issue_id> ignore [--json]
393  logbrew issue <issue_id> reopen [--json]
394  logbrew <issue_id> resolve [--json]
395  logbrew resolved <issue_id> [--json]
396  logbrew closed <issue_id> [--json]
397  logbrew ignored <issue_id> [--json]
398  logbrew open <issue_id> [--json]
399  logbrew unresolved <issue_id> [--json]
400
401Updates grouped issue status. Resolve/close map to resolved; ignore maps to ignored; reopen maps \
402                        to unresolved.
403Close is an alias for resolved.
404Issue-first, pasted-ID, and status-first aliases are useful after reading issue detail.
405Status values are case-insensitive.";
logbrew_cli/help.rs

logbrew_cli/
help.rs
