| 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 --> |