{"id":22484280,"url":"https://github.com/BetaHuhn/ackee-report","last_synced_at":"2025-08-02T17:32:26.258Z","repository":{"id":38426380,"uuid":"307180204","full_name":"BetaHuhn/ackee-report","owner":"BetaHuhn","description":"📈 CLI tool to generate performance reports of websites using the self-hosted analytics tool Ackee.","archived":false,"fork":false,"pushed_at":"2023-01-16T04:07:13.000Z","size":775,"stargazers_count":27,"open_issues_count":17,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-03T23:40:45.397Z","etag":null,"topics":["ackee","analytics","cli","email-report","privacy","website-analytics"],"latest_commit_sha":null,"homepage":"https://github.com/electerious/Ackee","language":"EJS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BetaHuhn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"ko_fi":"betahuhn","github":"betahuhn"}},"created_at":"2020-10-25T19:52:50.000Z","updated_at":"2024-06-10T21:10:23.000Z","dependencies_parsed_at":"2023-02-10T01:01:14.667Z","dependency_job_id":null,"html_url":"https://github.com/BetaHuhn/ackee-report","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Fackee-report","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Fackee-report/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Fackee-report/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Fackee-report/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BetaHuhn","download_url":"https://codeload.github.com/BetaHuhn/ackee-report/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228499948,"owners_count":17929978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ackee","analytics","cli","email-report","privacy","website-analytics"],"created_at":"2024-12-06T17:10:33.319Z","updated_at":"2025-08-02T17:32:26.247Z","avatar_url":"https://github.com/BetaHuhn.png","language":"EJS","funding_links":["https://ko-fi.com/betahuhn","https://github.com/sponsors/betahuhn"],"categories":["EJS"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \n\u003cimg src=\"https://cdn.mxis.ch/assets/ackee-report/logo.png\" title=\"ackee-report\" alt=\"ackee-report logo\" width=\"128\"\u003e\n\n# ackee-report\n\n[![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/BetaHuhn/ackee-report/blob/master/LICENSE) ![David](https://img.shields.io/david/betahuhn/ackee-report) [![npm](https://img.shields.io/npm/v/ackee-report)](https://www.npmjs.com/package/ackee-report)\n\nCLI tool to generate performance reports of websites using the self-hosted analytics tool Ackee.\n\n![preview](https://cdn.mxis.ch/assets/ackee-report/emailMockup.png)\n\n\n\u003c/div\u003e\n\n## 👋 Introduction\n\n[ackee-report](https://github.com/BetaHuhn/ackee-report) lets you create monthly website performance reports using your [Ackee](https://github.com/electerious/ackee) analytics data and either send them via email, generate a RSS feed or output it to a JSON file. It uses [Ackee's](https://github.com/electerious/ackee) Graphql API and can be configured to generate multiple reports for different websites, data ranges and recipients.\n\n## 🚀 Get started\n\nInstall [ackee-report](https://github.com/BetaHuhn/ackee-report) globally via npm:\n\n```shell\nnpm install ackee-report -g\n```\n\n\u003e ackee-report@latest requires Ackee \u003e=v3.1.1. Use ackee-report@v1.1.3 for older versions of Ackee\n\nAfter that `ackee-report` is ready to be used 🎉\n\n## ⚙️ Configuration\n\nOn the first run [ackee-report](https://github.com/BetaHuhn/ackee-report) will ask you to input a few values:\n\n- *ackee server* / `ACKEE_SERVER` - the endpoint of your Ackee instance\n- *ackee token* / `ACKEE_TOKEN` - a permanent Ackee token (can be used instead of username and password, [more info](#ackee-api-authentication))\n- *ackee username* `ACKEE_USERNAME` - your Ackee username ([more info](#ackee-api-authentication))\n- *ackee password* `ACKEE_PASSWORD` - your Ackee password ([more info](#ackee-api-authentication))\n- *email host* / `EMAIL_HOST` - the domain of the email server ([more info](#email-setup))\n- *email port* / `EMAIL_PORT` - the port of the email server ([more info](#email-setup))\n- *email username* / `EMAIL_USERNAME` - the username to use with the email server ([more info](#email-setup))\n- *email password* / `EMAIL_PASSWORD` - the password to use with the email server ([more info](#email-setup))\n- *email from* / `EMAIL_FROM` - the from address to use ([more info](#email-setup))\n\nThe configuration will be stored in your home directory under `~/.config/configstore/ackee-report.json` and can be changed at any point.\n\n### Environment Variables\n\nIf you don't want to interact with [ackee-report](https://github.com/BetaHuhn/ackee-report) via the CLI interface, you can also specify each configuration option as an environment variable e.g. `ACKEE_TOKEN=\u003ctoken\u003e`\n\n### Ackee API authentication\n\n[ackee-report](https://github.com/BetaHuhn/ackee-report) needs access to your Ackee instance via the API in order to get all the data it needs to generate the report. You can choose any of the two authentication methods below:\n\n**Username and password:**\n\nEnter your username and password you use to login to the Ackee UI on the first run of [ackee-report](https://github.com/BetaHuhn/ackee-report) or change it in the config file later.\n\n[ackee-report](https://github.com/BetaHuhn/ackee-report) will then use them to create a temporary access token each time it runs and use it to query the Ackee API.\n\n**Permanent access token (recommended):**\n\nThe recommended way of authenticating [ackee-report](https://github.com/BetaHuhn/ackee-report) is with a permanent access token (only available with Ackee [v2.2.0](https://github.com/electerious/Ackee/releases/tag/v2.2.0) or later). \n\nYou will have to create one via the Ackee UI under `Settings`/`Permanent Tokens`, then click on `New permanent token` and give it a name (doesn't matter what).\n\nCopy the `permanent token id` and enter it on the first run of [ackee-report](https://github.com/BetaHuhn/ackee-report) or add it to the config file under `ackee.token` later.\n\nThe same token will then be used each time [ackee-report](https://github.com/BetaHuhn/ackee-report) runs to query the Ackee API.\n\n### Email setup\n\nIf you want to send your report via email, you have to specify your email providers SMTP server and credentials, as well as the from option:\n\n- *Host* - `smtp.example.com`\n- *Port* - `465`\n- *Username* - `username@example.com`\n- *Password* - `password`\n- *From* - `username@example.com` or `Ackee \u003cusername@example.com\u003e`\n\n\u003e **Note:** For port 465 ackee-report will use TLS when connecting to your email server, on all other ports it will use STARTTLS (#44)\n\nCommon providers:\n\n\u003cdetails\u003e\u003csummary\u003eGmail\u003c/summary\u003e\n\nIf you use gmail to send emails, use these values:\n\n- *Host* - `smtp.gmail.com`\n- *Port* - `465`\n- *Username* -  your gmail username (your email address)\n- *Password* -  your gmail password or if you have 2FA enabled, an [\"Application Specific password\"](https://security.google.com/settings/security/apppasswords)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eSendGrid\u003c/summary\u003e\n\nIf you use SendGrid to send emails, use these values:\n\n- *Host* - `smtp.sendgrid.net`\n- *Port* - `465`\n- *Username* -  `apikey` (everyone's username is apiKey)\n- *Password* - your API Key (generate one [here](https://app.sendgrid.com/settings/api_keys))\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eMailGun\u003c/summary\u003e\n\nIf you use SendGrid to send emails, use these values:\n\n- *Host* - `smtp.mailgun.org`\n- *Port* - `465`\n- *Username* -  `postmaster@yourdomain.name`\n- *Password* - get your password [here](https://app.mailgun.com/app/domains)\n\n\u003c/details\u003e\n\n## 📚 Usage\n\n```shell\nUsage: ackee-report \u003ccommand\u003e [options]\n\nCLI tool to generate performance reports of websites using the self-hosted analytics tool Ackee.\n\nCommands:\n  email [options]             Generate report and send it via email\n  json [options]              Query API for data and output it to JSON file\n  html [options]              Generate report and output it to a HTML file\n  rss|xml [options]           Generate report as a RSS feed\n  domains|domain [titles...]  get domain id by title\n  config                      output current config\n  help [command]              display help for command\n\nOptions:\n  General:\n    -d, --domain \u003ctitles...\u003e    specify domains by title\n    -i, --id \u003cids...\u003e           specify domains by id\n    -r, --range \u003crange\u003e         specify data range (default: \"month\")\n    -l, --limit \u003cnumber\u003e        limit number of list items (default: 3)\n    -e, --events [type]         get event data (default: false)\n    -v, --version               output the version number\n    -h, --help                  display help for command\n\n  Email:\n    -t, --to \u003crecipient...\u003e     to whom the report should be sent\n\n  RSS/JSON/HTML:\n    -o, --output \u003cfile\u003e         path to output file (default: \"report.[xml/json/html]\")\n\nExample call:\n  $ ackee-report email --domain example.com --to hello@example.com\n```\n\nIf you want to send the report periodically, you have to setup a cron job which runs the command at a set interval (example below).\n\n## 🛠️ Examples\n\n### Generate a report for one domain and send it via email\n\n```shell\nackee-report email -d example.com -t hello@example.com\n```\n\nThis will generate a report for the domain `example.com` and send it via email to `hello@example.com`.\n\n### Multiple domains and recipients\n\n```shell\nackee-report email -d example.com example2.com -t hello@example.com hey@example2.com\n```\n\n### Include events in report\n\n```shell\nackee-report email -d all -t hello@example.com -e\n```\n\n### Average event type\n\n```shell\nackee-report email -d all -t hello@example.com -e avg\n```\n\n### Custom range\n\nYou can specify the data range of the report with the `-r`/`--range` option:\n\n```shell\nackee-report email -d example.com -t hello@example.com -r day\n```\n\nAvailable values: `day`/`week`/`month`/`six_months`.\n\n**Note:** The `total views/range` value is calculated by counting the views of the last x days since the program ran. For the `month` range for example, it is not the number of views in the current month, but the number of views in the last 30 days.\n\n### Send the report periodically (cron)\n\nTo send a report periodically, for example every month at the 28th at 23:55 setup a cron job like this:\n\n```shell\n55 23 28 * * ackee-report email -d example.com -t hello@example.com \u003e\u003e /tmp/ackee-report.log 2\u003e\u00261\n```\n\n**Note:** We use the 28th as running on the last day of the month is very complicated with cron and Ackee resets its data on the first day of each month.\n\n**Note:** You may have to specify the actual path to ackee-report. In that case, replace `ackee-report` in the command above with the output of `which ackee-report`.\n\nIf you are not familiar with cron, [here's](https://ostechnix.com/a-beginners-guide-to-cron-jobs/) a tutorial on how to get started.\n\nTo send multiple reports to different people, add them all as seperate cron jobs.\n\n### Generate RSS feed\n\nYou can generate a RSS feed/xml file instead of sending the report via email:\n\n```shell\nackee-report rss -d example.com -o output.xml\n```\n\n### Output the report to a JSON file\n\nYou can also save the report in a JSON file:\n\n```shell\nackee-report json -d example.com -o output.json\n```\n\n### Output the email report to a HTML file\n\nYou can also save the report, which is normally sent via email, directly to an HTML file:\n\n```shell\nackee-report html -d example.com -o index.html\n```\n\n## 🖼️ Screenshot\n\n![Full Report](https://cdn.mxis.ch/assets/ackee-report/reportFull.png)\n\n## 💻 Development\n\nIssues and PRs are very welcome!\n\nRun `yarn lint` or `npm run lint` to use eslint.\n\nPlease check out the [contributing guide](CONTRIBUTING.md) before you start.\n\nTo see differences with previous versions refer to the [CHANGELOG](CHANGELOG.md).\n\n## ❔ About\n\nThis library is an extension to the awesome privacy focused analytics tool [Ackee](https://github.com/electerious/ackee).\n\n[Ackee](https://github.com/electerious/ackee) was developed by [@electerious](https://github.com/electerious), if you want to support him and the development of Ackee visit [the Donate section](https://github.com/electerious/ackee#donate) on the Ackee repository.\n\n## License\n\nCopyright 2020 Maximilian Schiller\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBetaHuhn%2Fackee-report","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBetaHuhn%2Fackee-report","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBetaHuhn%2Fackee-report/lists"}