Debian Codegraph @

docs/usage/cli/generate/index.md

raw
1 # Generate
2
3 ## Overview
4
5 The `generate` command creates a notification service URL by guiding the user through an interactive process or using provided properties. If no service is specified, the command displays the list of supported services and exits.
6
7 ## Usage
8
9 ```bash title="Generate Command Syntax"
10 shoutrrr generate [FLAGS] <SERVICE> [GENERATOR]
11 ```
12
13 | Flag | Description |
14 |------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
15 | `-g, --generator string` | Specifies the generator to use (e.g., `basic`, `oauth2`, `telegram`). Defaults to a service-specific generator if available, or `basic` otherwise. |
16 | `-p, --property stringArray` | Provides configuration properties in `key=value` format (e.g., `token=abc123`). Multiple properties can be specified by repeating the flag. Invalid properties are reported but ignored. |
17 | `-s, --service string` | Specifies the notification service to generate a URL for (e.g., `discord`, `smtp`, `telegram`). Can also be provided as the first positional argument. |
18 | `-x, --show-sensitive` | Displays sensitive data (e.g., tokens, passwords) in the generated URL. By default, sensitive fields are masked with `REDACTED` for security. |
19
20 !!! Note
21 The `SERVICE` can be supplied as the first positional argument or using the `-s` flag. The `GENERATOR` can be supplied as the second positional argument or using the `-g` flag. If no generator is specified, a service-specific generator is used if available; otherwise, the `basic` generator is used.
22
23 ### Generators
24
25 #### Basic
26
27 The default generator that dynamically prompts for service configuration fields.
28
29 - Inspects service struct tags (`key`, `desc`, `default`) to generate prompts.
30 - Handles required fields by reprompting if values are missing.
31 - Integrates with `-p` properties to skip prompts for prefilled fields.
32
33 !!! Example
34 ```bash
35 shoutrrr generate discord -g basic
36 ```
37
38 #### OAuth2
39
40 Specialized generator for OAuth2 authentication in SMTP services.
41
42 - Supports JSON credential files (specified as a positional argument) or interactive prompts for details like Client ID, Client Secret, and Auth URL.
43 - Generates an authentication URL and exchanges verification codes for access tokens.
44 - Configures Gmail-specific defaults (port 587, STARTTLS, sender email as `FromAddress` and `ToAddresses`).
45
46 !!! Example
47 ```bash
48 shoutrrr generate smtp oauth2 -p provider=gmail credentials.json
49 ```
50
51 #### Telegram
52
53 Interactive generator tailored for Telegram bot and chat configuration.
54
55 - Prompts for bot token (from `@BotFather`) and fetches bot info.
56 - Listens for real-time messages to collect chat IDs (PMs, groups, channels).
57 - Supports dynamic chat addition via user interaction.
58 - Generates URL with token and selected chat IDs.
59
60 !!! Example
61 ```bash
62 shoutrrr generate telegram -g telegram
63 ```
64
65 ### Properties
66
67 Properties prefill configuration fields, reducing or eliminating interactive prompts.
68 For example, `-p token=abc123` sets the token field without prompting.
69
70 !!! Example
71 ```bash
72 shoutrrr generate discord -p token=abc123
73 ```
74
75 ### Services
76
77 Services like `telegram` and `smtp` (with `oauth2`) use specialized generators for a tailored experience, while others use the `basic` generator.
78
79 !!! Example
80 ```bash
81 shoutrrr generate -s discord
82 ```
83
84 ### Show Sensitive
85
86 Use this flag to view the full URL, including sensitive fields like tokens or passwords, for debugging or verification.
87
88 !!! Example
89 ```bash
90 shoutrrr generate smtp oauth2 -x -p provider=gmail credentials.json
91 ```
92
93 ## Examples
94
95 <!-- markdownlint-disable -->
96 ### Generate a Telegram URL with the Telegram Generator
97 !!! Example
98 ```bash
99 shoutrrr generate telegram -g telegram
100 ```
101
102 ```text
103 To start we need your bot token. If you haven't created a bot yet, you can use this link:
104 https://t.me/botfather?start
105
106 Enter your bot token: 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw
107 Fetching bot info...
108
109 Okay! @MyBot will listen for any messages in PMs and group chats it is invited to.
110 Waiting for messages to arrive...
111 Got Message 'Hello' from @User in private chat -100123456789
112 Added new chat User!
113 Got %0 chat ID(s) so far. Want to add some more? [Yes]: No
114 ```
115
116 ```text
117 Cleaning up the bot session...
118 Selected chats:
119 -100123456789 (private) User
120
121 URL: telegram://110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw@telegram?chats=-100123456789
122 ```
123
124 ### Generate a Discord URL with the Basic Generator
125
126 !!! Example
127 ```bash
128 shoutrrr generate discord
129 ```
130
131 ```text
132 Generating URL for discord using basic generator
133
134 Token: abc123
135 WebhookID: 123456789
136 ```
137
138 ```text
139 URL: discord://abc123@123456789
140 ```
141
142 ### Generate an SMTP URL with the OAuth2 Generator for Gmail
143
144 !!! Example
145 ```bash
146 shoutrrr generate smtp oauth2 -p provider=gmail credentials.json
147 ```
148
149 ```text
150 Generating URL for smtp using oauth2 generator
151
152 Visit the following URL to authenticate:
153 https://accounts.google.com/o/oauth2/auth?...
154 Enter verification code: 4/0AX4Xf...
155 Enter sender e-mail: [email protected]
156 ```
157
158 ```text
159 URL: smtp://[email protected]:[email protected]:587/?auth=OAuth2&[email protected]&[email protected]&fromname=Shoutrrr&usehtml=true&usestarttls=true
160 ```
161 <!-- markdownlint-restore -->