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> [--runtime <runtime>] [--source api|cli|sdk] \
233[--environment <environment>] [--json]
234
235Project creation, setup status, and project-scoped ingest credentials are backend-owned.
236Current mode: projects setup marks backend-owned setup as seen; project creation remains help only.
237No local project, install, quota, or usage state is created.
238Project setup uses POST /api/projects/{project_id}/setup/seen and preserves backend setup status JSON.
239Project-scoped SDK/ingest credentials are shown only when backend returns one-time credentials.
240Never use an account bearer token as SDK or ingest configuration.
241Next: run logbrew setup for the current non-mutating local plan.";
242
243/// Backend-owned usage and quota help text.
244const USAGE_HELP: &str = "\
245Usage:
246  logbrew usage [--json]
247  logbrew account usage [--json]
248
249Account usage, plan limits, quota state, reset dates, and per-project or per-stream breakdowns are \
250backend-owned.
251Current mode: help only. The CLI does not calculate or persist usage/quota state from local files.
252When backend usage is available, the CLI will read the backend account usage contract and preserve \
253stable JSON for agents.
254Next: run logbrew status to verify API and auth state.";
255
256/// Read command help text.
257const READ_HELP: &str = "\
258Usage:
259  logbrew read logs [filters] [--json]
260  logbrew read log [filters] [--json]
261  logbrew show logs [filters] [--json]
262  logbrew list issues [filters] [--json]
263  logbrew get issue <issue_id> [--json]
264  logbrew read issues [filters] [--json]
265  logbrew read actions [filters] [--json]
266  logbrew read releases [filters] [--json]
267  logbrew read release [filters] [--json]
268  logbrew read trace <trace_id> [--json]
269  logbrew read issue <issue_id> [--json]
270
271Reads historical observability data for agents and developers.
272Singular read aliases: logbrew read log, read release, show log, list issue, get release.
273Recency counts are limit shortcuts: logbrew last 10 logs or logbrew recent 5 issues.
274Use --environment <environment> with logs, issues, actions, releases, or traces.
275Filter aliases: --env, --project-id, --trace-id, and --distinct-id.";
276
277/// Read logs help text.
278const READ_LOGS_HELP: &str = "\
279Usage:
280  logbrew read logs [--severity error] [--search checkout] [--release <release>] [--environment \
281                              production] [--since 24h] [--trace <trace_id>] [--project \
282                              <project_id>] [--limit 100] [--json]
283  logbrew logs checkout failed [--severity error] [--release <release>] [--environment \
284                              production] [--json]
285  logbrew logs error checkout failed [--release <release>] [--environment production] [--json]
286
287Reads structured logs. Severity values are info, warning, error, and critical.
288Legacy severity aliases are accepted on input and normalized.
289Severity matching is case-insensitive. --level is accepted as a compatibility alias for \
290                              --severity.
291The logs shortcut accepts obvious multi-word search text, such as logbrew logs checkout failed.
292Shortcut levels can include search text, such as logbrew logs error checkout failed.
293Recency counts are limit shortcuts, such as logbrew last 10 logs.
294Explicit filters accept unquoted search text too, such as logbrew logs --severity warning checkout \
295                              failed or logbrew logs --search checkout failed.
296Use -- before literal flag-looking search text, such as logbrew logs -- --timeout --json.
297Filter by severity, message search, release, or trace_id to correlate logs with spans.
298Limit must be a positive whole number.";
299
300/// Read issues help text.
301const READ_ISSUES_HELP: &str = "\
302Usage:
303  logbrew read issues [--release <release>] [--environment production] [--status unresolved] \
304                                [--project <project_id>] [--limit 100] [--json]
305  logbrew issues open [--release <release>] [--environment production] [--json]
306  logbrew issue open [--release <release>] [--environment production] [--json]
307  logbrew open issues [--release <release>] [--environment production] [--json]
308  logbrew open issue [--release <release>] [--environment production] [--json]
309  logbrew last 5 open issues [--json]
310  logbrew errors closed [--release <release>] [--environment production] [--json]
311
312Reads grouped issues across releases and environments.
313Status accepts unresolved/open, resolved/closed, or ignored, case-insensitively.
314Issue shortcuts accept status words, such as logbrew issues open, logbrew issue open, logbrew open \
315                                issues, logbrew open issue, or logbrew errors closed.
316Recency issue shortcuts can include status and count, such as logbrew last 5 open issues.
317Limit must be a positive whole number.";
318
319/// Read actions help text.
320const READ_ACTIONS_HELP: &str = "\
321Usage:
322  logbrew read actions [--release <release>] [--environment production] [--name checkout_failed] \
323                                 [--user <distinct_id>] [--since 24h] [--project <project_id>] \
324                                 [--limit 100] [--json]
325  logbrew events checkout_failed [--release <release>] [--environment production] [--json]
326
327Reads product actions. Use distinct_id to follow one actor or session.
328Action/event aliases accept one positional name as the same filter as --name.
329Limit must be a positive whole number.";
330
331/// Read releases help text.
332const READ_RELEASES_HELP: &str = "\
333Usage:
334  logbrew read releases [--release <release>] [--environment production] [--project <project_id>] \
335                                  [--limit 100] [--json]
336
337Reads release summaries with counts for issues, logs, trace spans, and actions.
338Limit must be a positive whole number.";
339
340/// Read trace help text.
341const READ_TRACE_HELP: &str = "\
342Usage:
343  logbrew read trace <trace_id> [--release <release>] [--environment production] [--project \
344                               <project_id>] [--json]
345
346Reads spans for one distributed trace.";
347
348/// Read issue help text.
349const READ_ISSUE_HELP: &str = "\
350Usage:
351  logbrew read issue <issue_id> [--json]
352
353Reads one grouped issue with status, release, environment, and occurrence counts.";
354
355/// Watch command help text.
356const WATCH_HELP: &str = "\
357Usage:
358  logbrew watch --json
359  logbrew watch logs [--json]
360  logbrew watch issues [--json]
361  logbrew watch actions [--json]
362  logbrew watch --severity error,critical --json
363
364Aliases: tail, follow, and stream use the same live watch flow.
365Live watch uses a short-lived feed ticket and WebSocket stream.
366Transient disconnects reconnect with a fresh ticket and backoff.
367Server-side live filters are not sent yet; severity filtering is applied client-side.";
368
369/// Explain command help text.
370const EXPLAIN_HELP: &str = "\
371Usage:
372  logbrew explain issue <issue_id> [--json]
373  logbrew explain trace <trace_id> [--json]
374  logbrew explain <issue_id_or_trace_id> [--json]
375  logbrew issue <issue_id> explain [--json]
376  logbrew trace <trace_id> explain [--json]
377  logbrew <issue_id_or_trace_id> explain [--json]
378
379Fetches enough context for an AI agent to explain what happened.
380Pasted UUID/issue_* values are treated as issues; 32-hex/trace_* values are treated as traces.";
381
382/// Set command help text.
383const SET_HELP: &str = "\
384Usage:
385  logbrew set issue <issue_id> unresolved [--json]
386  logbrew set issue <issue_id> resolved [--json]
387  logbrew set issue <issue_id> ignored [--json]
388  logbrew resolve <issue_id> [--json]
389  logbrew close <issue_id> [--json]
390  logbrew ignore <issue_id> [--json]
391  logbrew reopen <issue_id> [--json]
392  logbrew issue <issue_id> resolve [--json]
393  logbrew issue <issue_id> close [--json]
394  logbrew issue <issue_id> ignore [--json]
395  logbrew issue <issue_id> reopen [--json]
396  logbrew <issue_id> resolve [--json]
397  logbrew resolved <issue_id> [--json]
398  logbrew closed <issue_id> [--json]
399  logbrew ignored <issue_id> [--json]
400  logbrew open <issue_id> [--json]
401  logbrew unresolved <issue_id> [--json]
402
403Updates grouped issue status. Resolve/close map to resolved; ignore maps to ignored; reopen maps \
404                        to unresolved.
405Close is an alias for resolved.
406Issue-first, pasted-ID, and status-first aliases are useful after reading issue detail.
407Status values are case-insensitive.";
logbrew_cli/help.rs

logbrew_cli/
help.rs
