diff --git a/README.md b/README.md index ecd9cc3..80e165b 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,6 @@ MyWhoop is a tool intended to help you take ownership of your Whoop data. You ca - 🗄️ **Server**: Automatically download your Whoop data daily and save it to a local file or export it to a remote location. - 📬 **Notifications**: Receive notifications when new data is available or when an error occurs. - 💾 **Data Export**: Export your Whoop data to a remote location such as an S3 bucket. -- ## Get Started 🚀 @@ -34,7 +33,6 @@ MyWhoop supports the following commands and global flags: - [Server](#server) - Automatically download your Whoop data daily and save it to a local file or export it to a remote location. - [Version](#version) - Display the version of MyWhoop. - #### Global Flags | Flag | Description | Required | Default | @@ -75,31 +73,5 @@ mywhoop login -## Environment Variables - -The following environment variables are available for use with MyWhoop. - -| Variable | Description | Required | -|---|----|---| -| `WHOOP_CLIENT_ID` | The client ID for your Whoop application. | Yes | -| `WHOOP_CLIENT_SECRET` | The client secret for your Whoop application. | Yes | -| `WHOOP_CREDENTIALS_FILE` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. Default value is `token.json`. | No | - - -### Notification Variables - -Depending on the notification service you use, you may need to provide additional environment variables. - -| Variable | Description | Required | -|---|----|---| -| `NOTIFICATION_NTFY_AUTH_TOKEN`| The token for the [Ntfy](https://docs.ntfy.sh/) service. Required if the ntfy subscription requires a token. | No | -| `NOTIFICATION_NTFY_PASSWORD` | The password for the ntfy subscription if username/password authentication is used. Required if the ntfy subscription requires a username and password. | No | - -### Order Of Precendence - -The order of precendence is as follows. -1. CLI flags. -2. Environment Variables -3. Configuration File diff --git a/docs/configuration_reference.md b/docs/configuration_reference.md index 927ccfa..9fbe136 100644 --- a/docs/configuration_reference.md +++ b/docs/configuration_reference.md @@ -1,8 +1,39 @@ # Configuration Reference -The MyWhoop configuration file is used to configure the behavior of MyWhoop and enable advanced features. The configuration file is a YAML file that is located at `~/.mywhoop.yaml` by default. The configuration file can be overridden by using the `--config` flag when issuing MyWhoop commands. +The MyWhoop configuration file is used to configure MyWhoop's behavior and enable advanced features. By default, it is a YAML file located at `~/.mywhoop.yaml`. You can override the configuration file by using CLI flags. +> [!IMPORTANT] +> You can learn more about supported environment variables in the [Environment Variables](./environment_variables.md) section. + + + +## Credentials + +The credentials section of the configuration file is used to configure where the MyWhoop authentication token is stored or where to find it. The following fields are available for configuration: + +| Field | Description | Required | Default | +|---|----|---|---| +| `credentialsFile` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. By default, MyWhoop looks for a token file in the local directory. | No | `token.json` | + +```yaml +credentials: + credentialsFile: "/opt/mywhoop/token.json" +``` + +## Debug + +The debug section of the configuration file is used to enable debug logging for MyWhoop. The following fields are available for configuration: + +| Field | Description | Required | Default | +|---|----|---|---| +| `debug` | Enable debug logging. Allowed values are: `INFO`, `DEBUG`, `WARN`, and `ERROR`. | No | `INFO` | + + +```yaml +debug: "info" +``` + ## Export The export section of the configuration file is used to configure the data export feature of MyWhoop. The export feature allows you to export your Whoop data to a remote location such as an S3 bucket. The following fields are available for configuration: @@ -23,7 +54,7 @@ Local file export accepts the following fields. | `fileName` | The name of the file to export. | Yes | `user` | | `filePath` | The path to save the file. By default, a data folder is created in the immediate folder. | Yes | `data/` | | `fileType` | The file type to save the file as. Allowed values are `json`. | Yes | `json` | -| `fileNamePrefix` | The prefix to add to the file name. In server mode, the data is automatically inserted as a prefix. | No | | +| `fileNamePrefix` | The prefix to add to the file name. In server mode, the data is automatically inserted as a prefix. | No |`""` | | `serverMode` | Ensures the file name is unique and contains a timestamp. Ensures behaviors match server mode. | No | `false` | ```yaml @@ -38,7 +69,7 @@ export: ### S3 Export -S3 export accepts the following fields. +You can export your Whoop data to an AWS S3 bucket using the S3 export method. By default, AWS credentials are honored from the environment variables or the default profile in the [order of precedence of the AWS SDK](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials). The S3 export method accepts the following fields: | Field | Description | Required | Default | |---|----|---|---| @@ -60,15 +91,98 @@ export: fileNamePrefix: "" serverMode: true ``` -## Credentials -The credentials section of the configuration file is used to configure where the Whoop authentication token is stored or where to find it. The following fields are available for configuration: +## Notification + +The notification section of the configuration file is used to configure the notification feature of MyWhoop. By default, notifications are sent to stdout. The notification feature allows you to use a different service to receive notifications when MyWhoop completes a task. The following fields are available for configuration: | Field | Description | Required | Default | |---|----|---|---| -| `credentialsFile` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. By default, MyWhoop looks for a token file in the local directory. | No | `token.json` | +|`method` | The notification method to use. Allowed values are `ntfy`, or `""`. | Yes | `""`| +| `ntfy` | The ntfy notification configuration. Required if `method` is `ntfy`. | No | | + +### Ntfy + +You can use the open-source service, [Ntfy](https://docs.ntfy.sh/), to receive notifications when MyWhoop completes a task or an error is encountered. The Ntfy configuration block accepts the following fields: + +| Field | Description | Required | Default | +|---|----|---|---| +| `events` | The events to receive notifications for. Allowed values are `""`, `all`, `success`, and `error`. | Yes | `all` | +| `serverEndpoint` | The Ntfy server endpoint to send notifications to. | Yes | `""` | +| `subscriptionID` | The subscription ID to use for the Ntfy subscription. | Yes | `""` | +| `userName` | The username for the Ntfy subscription. Required if user name and password is used. | No | `""` | + +```yaml +notification: + method: "ntfy" + ntfy: + serverEndpoint: "https://example.my.ntfy.com" + subscriptionID: "mywhoop_custom_notifications" + events: "all" +``` + +> [!IMPORTANT] +> Use the environment variables `NOTIFICATION_NTFY_AUTH_TOKEN` or `NOTIFICATION_NTFY_PASSWORD` to provide the Ntfy authentication credentials. + + + +## Server + +The server section of the configuration file is used to configure the server feature of MyWhoop. The server feature allows you to start MyWhoop as a server that queries the Whoop API every 24 hours. The following fields are available for configuration: + +| Field | Description | Required | Default | +|---|----|---|---| +| `enabled` | Enable the server feature. | No | `false` | +| `firstRunDownload` | Download the data on the first run. This is not a recommended flag for server mode as it will re-download all the Whoop data on a server or machine reboot. | No | `false` | + ```yaml +server: + enabled: true + firstRunDownload: false +``` + + +## Example Configuration File + + +The following is an example configuration file that configures MyWhoop to export data to an S3 bucket, enable the server feature, and send notifications using the Ntfy service. + +```yaml +export: + method: s3 + awsS3: + region: "us-east-1" + bucket: "42acg-primary-data-whoop-bucket" + fileConfig: + fileName: "" + fileType: "json" + fileNamePrefix: "" + serverMode: true +server: + enabled: true + firstRunDownload: false +notification: + method: "ntfy" + ntfy: + serverEndpoint: "https://ntfy.self-hosted.example" + subscriptionID: "mywhoop_alerts_at_home" + events: "all" +debug: info +``` + + +The following is an example configuration file configuring MyWhoop to export data to a local file and enabling debug logging. + +```yaml +export: + method: file + fileExport: + fileName: "user" + filePath: "/opt/mywhoop/data/" + fileType: "json" + fileNamePrefix: "" credentials: - credentialsFile: "/opt/mywhoop/token.json" + credentialsFile: "/opt/mywhoop/token.json" +debug: debug ``` \ No newline at end of file diff --git a/docs/environment_variables.md b/docs/environment_variables.md new file mode 100644 index 0000000..60974d8 --- /dev/null +++ b/docs/environment_variables.md @@ -0,0 +1,35 @@ +# Environment Variables + + +MyWhoop uses environment variables to configure the application. The environment variables are used to configure the Whoop API client and other integrations such as notifications. + +### Order Of Precendence + +The order of precendence is as follows. + +1. CLI flags. +2. Environment Variables +3. Configuration File + + +## MyWhoop Variables + +The following environment variables are used to configure MyWhoop. The two required variables are `WHOOP_CLIENT_ID` and `WHOOP_CLIENT_SECRET`. + + +| Variable | Description | Required | +|---|----|---| +| `WHOOP_CLIENT_ID` | The client ID for your Whoop application. | Yes | +| `WHOOP_CLIENT_SECRET` | The client secret for your Whoop application. | Yes | +| `WHOOP_CREDENTIALS_FILE` | The file path to the Whoop credentials file that contains a valid Whoop authentication token. Default value is `token.json`. | No | + + +### Notification Variables + +Depending on the notification service you use, you may need to provide additional environment variables. + +| Variable | Description | Required | +|---|----|---| +| `NOTIFICATION_NTFY_AUTH_TOKEN`| The token for the [Ntfy](https://docs.ntfy.sh/) service. Required if the ntfy subscription requires a token. | No | +| `NOTIFICATION_NTFY_PASSWORD` | The password for the ntfy subscription if username/password authentication is used. Required if the ntfy subscription requires a username and password. | No | +