{"id":15885776,"url":"https://github.com/toniov/gcalcron","last_synced_at":"2025-10-04T10:18:28.395Z","repository":{"id":66268145,"uuid":"104167756","full_name":"toniov/gcalcron","owner":"toniov","description":"Schedule shell commands execution through Google Calendar","archived":false,"fork":false,"pushed_at":"2017-12-14T02:35:39.000Z","size":139,"stargazers_count":84,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-02-28T23:47:28.039Z","etag":null,"topics":["command-line-tool","cron","google-apis","google-calendar","nodejs","scheduled-tasks"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toniov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-20T05:00:18.000Z","updated_at":"2024-02-10T18:29:13.000Z","dependencies_parsed_at":"2023-06-04T07:14:48.756Z","dependency_job_id":null,"html_url":"https://github.com/toniov/gcalcron","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"80476a0fb8c0600c85aa9f684c7419054aa89a88"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toniov%2Fgcalcron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toniov%2Fgcalcron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toniov%2Fgcalcron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toniov%2Fgcalcron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toniov","download_url":"https://codeload.github.com/toniov/gcalcron/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244059508,"owners_count":20391344,"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":["command-line-tool","cron","google-apis","google-calendar","nodejs","scheduled-tasks"],"created_at":"2024-10-06T05:07:49.992Z","updated_at":"2025-10-04T10:18:28.390Z","avatar_url":"https://github.com/toniov.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gcalcron\n\n\u003e Schedule shell commands execution through Google Calendar\n\n`Google Calendar` + `Cron` + `Node.js`\n\n## Super fast usage example\n\nStart gcalcron:\n\n```\n$ gcalcron start '0 0 10 * * *'\n\n[INFO] Process started checking your calendar: 10:00:00 every day\n```\n\nInsert an event starting at 10:00 through Google Calendar:\n\n\u003cimg src=\"./shortcut-gcal.png\" width=\"400\"\u003e\n\nBack in the terminal:\n\n```\n[INFO] Executed: 'ls -l | grep file.txt'\n-rw-r--r--    1 antonio  1796131739     11 Sep 24 15:14 file.txt\n```\n\n## Installation\n\nInstall it as a global module:\n\n```\n$ npm install -g gcalcron\n```\n\n## Usage\n\n1. Authenticate the app\n2. Start `gcalcron`, setting the check interval using cron syntax\n3. Schedule tasks inserting events in your calendar\n\n### 1. Authentication\n\nAuthorization and authentication is done with OAuth 2.0. \n\nOk, this will take only about 2 minutes:\n\n#### 1.1 Get your project credentials\n\nYou will need a file with your credentials: `client ID`, `client secret` and `redirect URI`. This can be obtained in the [Developer Console](https://console.developer.google.com):\n\n- Go to your project\n- Click in `Credentials`\n- Click `Create credentials` → `OAuth client ID` (`Application type` must be `Other`)\n- Download the JSON file\n\n#### 1.2 Generate consent page URL\n\nOnce we got the credentials we must generate a consent page URL.\n\n```\n$ gcalcron generateUrl\n```\n\n([By default](#setting-your-own-config), the credentials will be searched in your home directory under the name `client_secret.json`)\n\nThe page will prompt you to authorize access, follow the instructions.\n\n#### 1.3 Get the token!\n\nWith the code we got through the authorization page, we can obtain a token and store it in our machine.\n\n```\n$ gcalcron storeToken \u003ccode\u003e\n```\n\n([By default](#setting-your-own-config), the token is stored in your home folder under the name `calendar_api_token.json`). \n\nNOTE: The token will expiry after one hour, but a `refresh_token` is included as well, allowing the app to refresh automatically the token each time it's used.\n\nWith this we are good to go. The stored token and credentials files will be required from now on to use this tool.\n\n### 2. Start gcalcron\n\nSyntax:\n\n```\ngcalcron start \u003ccron-time\u003e [--out \u003cfile\u003e --err \u003cfile\u003e]\n```\n\n`\u003ccron-time\u003e` must be in the form of cron syntax, with this the check frequency will be set.\n\n`--out \u003cfile\u003e` and `--err \u003cfile\u003e` are optional, executed commands output and error output can be set using these options. By default, `stdio` and `sterr` will be used.\n\nThe next example will check your Google Calendar every hour printing the executed commands output in a text file:\n\n```\n$ gcalcron start '0 0 * * * *' --out ./output.txt\n```\n\nThe Cron functionality is powered by [node-cron](https://github.com/kelektiv/node-cron), for more info about the syntax check the repository README.\n\n### 3. Schedule tasks through Google Calendar\n\n#### Event title\n\nThe events have to start with `Execute: `, followed by the shell command you want to execute.\n\n```\nExecute: /some/random/script.sh\n```\n\n#### Event description\n\nThe command can be specified in the event description instead, in case the description has content, the command in the title will be ignored.\n\nNOTE: `Execute:` must be written always, what is ignored is whatever is written after `Execute:`.\n\n#### Event start and end time\n\nThe range of time when the command will be executed. It will be executed only once, after it's executed the title of the event is renamed to from `Execute: foo` to `[Executed] foo`.\n\nRecurring events will be executed once per occurrence.\n\nNOTE: If, for example, an event is set from 20:00 to 21:00, you have to make sure that `gcalcron` is going to check your calendar at least once per hour.\n\n## Setting your own config\n\nUsing the option `-C \u003cfile\u003e` you can set your own config. This file must be `.js` or `.json`.\n\n**Example:**\n\n`/somepath/config.json`\n```json\n{\n  \"CRED_PATH\": \"/my/secret/path/credentials.json\",\n  \"TOKEN_PATH\": \"/my/secret/path/token.json\",\n}\n```\n\n```\n$ gcalcron -C /somepath/config.json generateUrl\n\n$ gcalcron -C /somepath/config.json storeToken 1249asdjasop12\n\n$ gcalcron -C /somepath/config.json start \"0,30 * * * * *\"\n```\n\nWith the above config your token will be stored in `/my/secret/path/credentials.json`, and your token and credentials will be read from there as well.\n\n**The available options are:**\n\n### CRED_PATH\n\nPath to your credentials file. (Default: located in your home directory under the name `client_secret.json`)\n\n### TOKEN_PATH\n\nPath to your token. (Default: located in your home directory under the name `calendar_api_token.json`)\n\n### CALENDAR_ID\n\nThe ID of the calendar you want to use. (Default: `primary` calendar)\n\n### LIST_ORDER\n\nIn case there are several events to be executed, this set the execution order (always ascending). Acceptable values are `updated` and `startTime`. (Default: `startTime`)\n\n### OUT_PATH\n\nWrite command output to a an specified file. (Default: `stdout`).\n\nSame as the option `-o, --output \u003cfile\u003e`. In case both are set, the option has preference.\n\n### ERR_PATH\n\nWrite command errors to a an specified file. (Default: `stderr`)\n\nSame as the option `-e, --error \u003cfile\u003e`. In case both are set, the option has preference.\n\n### SHELL\n\nShell to execute the command with. (Default: `/bin/sh` on UNIX, `process.env.ComSpec` on Windows)\n\n## API\n\nUse the `help` command.\n\n**`$ gcalcron help`**\n\n## Considerations\n\n- Use it under your own risk, if your Google Calendar account is compromised, malicious code could be executed.\n- The Google Calendar API has a [limit](https://developers.google.com/google-apps/calendar/pricing) of 1,000,000 queries per day, so it should be enough even if the check is executed once per second.\n- If you want to keep the process alive, consider using some tools like [PM2](https://github.com/Unitech/pm2) or [forever](https://github.com/foreverjs/forever).\n\n## Related\n\n`gcalcron` can be used altogether with [gcal](https://github.com/toniov/gcal-cli) to insert events programmatically. They share the same authentication process, so you can get to use it out-of-the-box.\n\n## License\n\nMIT © [Antonio V](https://github.com/toniov)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoniov%2Fgcalcron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoniov%2Fgcalcron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoniov%2Fgcalcron/lists"}