{"id":31741154,"url":"https://github.com/yanicksenn/gtasks-cli","last_synced_at":"2025-10-09T10:47:19.139Z","repository":{"id":305042791,"uuid":"1021637685","full_name":"yanicksenn/gtasks-cli","owner":"yanicksenn","description":"A command-line interface (CLI) for managing your Google Tasks.","archived":false,"fork":false,"pushed_at":"2025-08-19T11:29:45.000Z","size":101093,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-23T17:22:45.730Z","etag":null,"topics":["cli","google-tasks","productivity"],"latest_commit_sha":null,"homepage":"","language":"Go","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/yanicksenn.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,"zenodo":null}},"created_at":"2025-07-17T17:47:49.000Z","updated_at":"2025-08-19T11:29:49.000Z","dependencies_parsed_at":"2025-07-18T03:23:37.563Z","dependency_job_id":"9ac18bcf-a9dd-4e4f-a7d1-b0268c1abc79","html_url":"https://github.com/yanicksenn/gtasks-cli","commit_stats":null,"previous_names":["yanicksenn/workspace","yanicksenn/gtasks-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yanicksenn/gtasks-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanicksenn%2Fgtasks-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanicksenn%2Fgtasks-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanicksenn%2Fgtasks-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanicksenn%2Fgtasks-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yanicksenn","download_url":"https://codeload.github.com/yanicksenn/gtasks-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanicksenn%2Fgtasks-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001276,"owners_count":26083040,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cli","google-tasks","productivity"],"created_at":"2025-10-09T10:47:18.034Z","updated_at":"2025-10-09T10:47:19.133Z","avatar_url":"https://github.com/yanicksenn.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gtasks CLI\n\nA command-line interface (CLI) for managing your Google Tasks.\n\n## 0. Installation\n\n### Homebrew\n\n```sh\nbrew tap yanicksenn/gtasks-cli\nbrew install gtasks-cli\ngtasks help\n```\n\n### Go\n\n```sh\ngo install github.com/yanicksenn/gtasks-cli@latest\ngtasks-cli help\n```\n\n## Configuration\n\n`gtasks-cli` stores its configuration in a file named `config.json` in the following locations:\n\n*   **Linux:** `~/.config/gtasks/config.json`\n*   **macOS:** `~/Library/Application Support/gtasks/config.json`\n*   **Windows:** `%APPDATA%\\gtasks\\config.json`\n\nThe configuration file has the following structure:\n\n```json\n{\n  \"active_account\": \"user@example.com\"\n}\n```\n\n*   `active_account`: The email address of the currently active Google account.\n\n## 1. Building and Running\n\n### Prerequisites\n\n*   Go 1.20 or later\n\n### Building\n\nTo build the `gtasks` binary, run the following command from the root of the project:\n\n```sh\ngo build -o gtasks .\n```\n\nThis will place the executable file named `gtasks` in the project root.\n\n### Running\n\nTo run the application, first, you need to authenticate with your Google account:\n\n```sh\n./gtasks accounts login\n```\n\nThis will open a browser window for you to complete the authentication process.\n\nOnce authenticated, you can use the other commands, for example:\n\n```sh\n./gtasks tasklists list\n```\n\n### Running Tests\n\nTo run the full suite of tests, use the following command from the root of the project:\n\n```bash\ngo test ./...\n```\n\nThis command executes all unit and integration tests against a high-fidelity, in-memory mock of the Google Tasks API, ensuring that no real network calls are made and no authentication is required. It also runs the basic E2E tests.\n\n## Table of Contents\n\n- [1. Authentication](#1-authentication)\n- [2. Command Structure](#2-command-structure)\n- [3. Offline Mode](#3-offline-mode)\n- [4. Terminology](#4-terminology)\n- [5. Command Reference](#5-command-reference)\n  - [Account Management](#account-management)\n  - [TaskList Management](#tasklist-management)\n  - [Task Management](#task-management)\n- [6. Examples](#6-examples)\n- [7. Interactive Mode](#7-interactive-mode)\n- [8. Error Handling](#8-error-handling)\n- [9. Implementation Details](#9-implementation-details)\n\n---\n\n## 1. Authentication\n\n- **Google Sign-In:** The CLI authenticates with Google using OAuth 2.0.\n- **Credential Caching:** Caches credentials locally for automatic use until they expire.\n- **Token Refresh:** Automatically refreshes expired tokens.\n- **Multi-Account Support:** Manage multiple Google accounts seamlessly.\n\n## 2. Command Structure\n\nThe CLI follows a `gtasks \u003cresource\u003e \u003caction\u003e [flags]` pattern.\n\n- **`resource`**: The type of object to operate on (e.g., `accounts`, `tasklists`, `tasks`).\n- **`action`**: The operation to perform (e.g., `list`, `create`, `get`, `update`, `delete`).\n\n### Global Flags\n\n- `--offline`: Enable offline mode.\n- `--output` (string, optional): Output format. One of `table`, `json`, or `yaml`. Defaults to `table`.\n- `--quiet`, `-q` (boolean, optional): Suppress all output.\n- `--version`, `-v`: Print the version number.\n\n## 3. Offline Mode\n\n`gtasks` supports a full offline mode. By using the global `--offline` flag, you can manage your tasks and task lists without an internet connection. All changes are saved to a local file (`~/.config/gtasks/offline.json`).\n\n### Syncing Offline Changes\n\nSynchronization must be handled manually. To sync your offline changes, you need to be online and run the commands again without the `--offline` flag. For example, if you created a new task offline:\n\n```sh\n./gtasks tasks create --title \"My new task\" --offline\n```\n\nTo sync this task with Google Tasks, run the same command again without the `--offline` flag:\n\n```sh\n./gtasks tasks create --title \"My new task\"\n```\n\nThis will create the task in your Google Tasks. Similarly, for other commands like `update` and `delete`, you need to re-run them without the `--offline` flag to sync the changes.\n\n---\n\n## 4. Terminology\n\n- **Account:** Refers to the Google Account you authenticate with via the SSO sign-in flow. The CLI can cache multiple accounts, but only one is active at a time.\n- **TaskList:** A container for your tasks. A user can have multiple task lists to organize different areas of their life (e.g., \"Work,\" \"Groceries,\" \"Personal Projects\"). Each task list has a unique ID.\n- **Task:** A single to-do item that exists within a specific TaskList. It has properties like a title, notes, due date, and a completion status. Each task has a unique ID.\n- **@default TaskList:** This is a special identifier that refers to the user's default task list. Google Tasks automatically creates a default list for every user, which is typically named \"My Tasks\". `gtasks-cli` uses this as the default tasklist for all task-related commands unless a specific tasklist is provided with the `--tasklist` flag.\n\n---\n\n## 5. Command Reference\n\n### Account Management\n\nManage your authenticated Google accounts.\n\n#### `gtasks accounts login`\nInitiates the Google SSO flow to authenticate a new user. The new account becomes the active one.\n- **Usage:** `gtasks accounts login`\n\n#### `gtasks accounts logout`\nRemoves the cached credentials for the currently active user.\n- **Usage:** `gtasks accounts logout`\n\n#### `gtasks accounts list`\nLists all authenticated Google accounts.\n- **Usage:** `gtasks accounts list`\n\n#### `gtasks accounts switch`\nSwitches the active user to another authenticated account.\n- **Usage:** `gtasks accounts switch \u003cemail\u003e`\n- **Arguments:**\n  - `\u003cemail\u003e` (required): The email address of the account to make active.\n\n---\n\n### TaskList Management\n\nManage your task lists.\n\n#### `gtasks tasklists list`\nLists all task lists.\n- **Usage:** `gtasks tasklists list [flags]`\n- **Flags:**\n  - `--sort-by` (string, optional): Sort task lists by `alphabetical`, `last-modified`, or `uncompleted-tasks`. Defaults to `alphabetical`.\n\n#### `gtasks tasklists get`\nRetrieves the details of a specific task list.\n- **Usage:** `gtasks tasklists get \u003ctasklist_id\u003e`\n- **Arguments:**\n  - `\u003ctasklist_id\u003e` (required): The ID of the task list to retrieve.\n\n#### `gtasks tasklists create`\nCreates a new task list.\n- **Usage:** `gtasks tasklists create --title \u003clist_title\u003e`\n- **Flags:**\n  - `--title` (string, required): The title for the new task list.\n\n#### `gtasks tasklists update`\nUpdates the title of an existing task list.\n- **Usage:** `gtasks tasklists update \u003ctasklist_id\u003e --title \u003cnew_title\u003e`\n- **Arguments:**\n  - `\u003ctasklist_id\u003e` (required): The ID of the task list to update.\n- **Flags:**\n  - `--title` (string, required): The new title for the task list.\n\n#### `gtasks tasklists delete`\nPermanently deletes a task list and all of its tasks.\n- **Usage:** `gtasks tasklists delete \u003ctasklist_id\u003e`\n- **Arguments:**\n  - `\u003ctasklist_id\u003e` (required): The ID of the task list to delete.\n\n\n\n### Task Management\n\nManage your tasks within a task list.\n\n#### `gtasks tasks list`\nLists tasks within a specific task list.\n- **Usage:** `gtasks tasks list [--tasklist \u003ctasklist_id\u003e] [flags]`\n- **Flags:**\n  - `--tasklist` (string, optional): The ID of the task list. Defaults to `@default`.\n  - `--show-completed` (boolean, optional): Include completed tasks.\n  - `--show-hidden` (boolean, optional): Include hidden tasks.\n  - `--title-contains` (string, optional): Filter tasks by title (case-insensitive).\n  - `--notes-contains` (string, optional): Filter tasks by notes (case-insensitive).\n  - `--due-before` (string, optional): Filter tasks with a due date before a specified date (e.g., \"2025-12-31\").\n  - `--due-after` (string, optional): Filter tasks with a due date after a specified date (e.g., \"2025-12-31\").\n  - `--sort-by` (string, optional): Sort tasks by `alphabetical`, `last-modified`, or `due-date`. Defaults to `alphabetical`.\n\n#### `gtasks tasks get`\nRetrieves the details of a specific task.\n- **Usage:** `gtasks tasks get \u003ctask_id\u003e [--tasklist \u003ctasklist_id\u003e]`\n- **Arguments:**\n  - `\u003ctask_id\u003e` (required): The ID of the task.\n- **Flags:**\n  - `--tasklist` (string, optional): The ID of the task list containing the task. Defaults to `@default`.\n\n#### `gtasks tasks create`\nCreates a new task in a task list.\n- **Usage:** `gtasks tasks create --title \u003ctask_title\u003e [--tasklist \u003ctasklist_id\u003e]`\n- **Flags:**\n  - `--tasklist` (string, optional): The ID of the task list. Defaults to `@default`.\n  - `--title` (string, required): The title of the task.\n  - `--notes` (string, optional): Notes or description for the task.\n  - `--due` (string, optional): Due date in RFC3339 format (e.g., \"2025-12-31T22:00:00.000Z\").\n\n#### `gtasks tasks update`\nUpdates an existing task.\n- **Usage:** `gtasks tasks update \u003ctask_id\u003e [--tasklist \u003ctask_id\u003e] [flags]`\n- **Arguments:**\n  - `\u003ctask_id\u003e` (required): The ID of the task to update.\n- **Flags:**\n  - `--tasklist` (string, optional): The ID of the task list. Defaults to `@default`.\n  - `--title` (string, optional): The new title for the task.\n  - `--notes` (string, optional): The new notes for the task.\n  - `--due` (string, optional): The new due date in RFC3339 format.\n\n#### `gtasks tasks complete`\nMarks a task as complete.\n- **Usage:** `gtasks tasks complete \u003ctask_id\u003e [--tasklist \u003ctasklist_id\u003e]`\n- **Arguments:**\n  - `\u003ctask_id\u003e` (required): The ID of the task.\n- **Flags:**\n  - `--tasklist` (string, optional): The ID of the task list. Defaults to `@default`.\n\n#### `gtasks tasks uncomplete`\nMarks a task as not complete.\n- **Usage:** `gtasks tasks uncomplete \u003ctask_id\u003e [--tasklist \u003ctasklist_id\u003e]`\n- **Arguments:**\n  - `\u003ctask_id\u003e` (required): The ID of the task.\n- **Flags:**\n  - `--tasklist` (string, optional): The ID of the task list. Defaults to `@default`.\n\n#### `gtasks tasks delete`\nPermanently deletes a task.\n- **Usage:** `gtasks tasks delete \u003ctask_id\u003e [--tasklist \u003ctasklist_id\u003e]`\n- **Arguments:**\n  - `\u003ctask_id\u003e` (required): The ID of the task.\n- **Flags:**\n  - `--tasklist` (string, optional): The ID of the task list. Defaults to `@default`.\n\n\n\n## 6. Examples\n\nHere are some common commands to get you started.\n\n### Authenticate with Google\nThis is the first command you should run. It will open your web browser to the Google login page to authorize the application.\n```sh\n./gtasks accounts login\n```\n\n### List All Your Task Lists\n```sh\n$ ./gtasks tasklists list\nTask Lists:\n- My tasks (MTM1NTM2MzQzNzczNDkyNzc1NTQ6MDow)\n- Old Google Keep reminders (eUZqdFdsOGpsNVdUclY1Mg)\n```\n\n### Create a New Task List\n```sh\n$ ./gtasks tasklists create --title \"Groceries\"\nSuccessfully created task list: Groceries (OS0ydmR2N3NpSTQ4SzVVMA)\n```\n\n### List Tasks\nYou can list tasks in your default list or a specific list.\n\n```sh\n# List tasks in the default list\n$ ./gtasks tasks list\nTasks:\n[ ] buy toilet cleaners (U0QzVTI3TDFiRXg1NnJoSg)\n[ ] buy shampoo (VlFTcEt1TXItMl9RUDZpRg)\n...\n\n# List tasks in a specific list by its ID\n$ ./gtasks tasks list --tasklist \"OS0ydmR2N3NpSTQ4SzVVMA\"\nTasks:\n[ ] Buy milk (ZmFyb3FBSzJhUUlRZGJnWg)\n\n# Find all tasks with \"buy\" in the title\n$ gtasks tasks list --title-contains \"buy\"\nTasks:\n[ ] buy toilet cleaners (U0QzVTI3TDFiRXg1NnJoSg)\n[ ] buy shampoo (VlFTcEt1TXItMl9RUDZpRg)\n```\n\n### Create a New Task\nYou can create a simple task or add more details like a due date.\n\n```sh\n# Create a simple task in the default list\n$ ./gtasks tasks create --title \"Buy milk\"\nSuccessfully created task: Buy milk (eG9_b...)\n\n# Create a task with a due date in a specific list\n$ ./gtasks tasks create --tasklist \"OS0ydmR2N3NpSTQ4SzVVMA\" --title \"Finish report\" --due \"2025-12-20T15:00:00.000Z\"\nSuccessfully created task: Finish report (aG9_c...)\n```\n\n### Complete a Task\nTo complete a task, you need its ID, which you can get from the `tasks list` command.\n```sh\n$ ./gtasks tasks complete \"ZmFyb3FBSzJhUUlRZGJnWg\" --tasklist \"OS0ydmR2N3NpSTQ4SzVVMA\"\nSuccessfully completed task: Buy milk (ZmFyb3FBSzJhUUlRZGJnWg)\n```\n\n### View Completed Tasks\nUse the `--show-completed` flag to include completed tasks in the list.\n```sh\n$ ./gtasks tasks list --tasklist \"OS0ydmR2N3NpSTQ4SzVVMA\" --show-completed\nTasks:\n[x] Buy milk (ZmFyb3FBSzJhUUlRZGJnWg)\n```\n\n### Work Offline\nYou can use the `--offline` flag with most commands to work with a local copy of your tasks.\n```sh\n./gtasks tasklists list --offline\n```\n\n### Advanced Examples\n\n#### Filtering Tasks\n\nYou can combine filters to narrow down your search.\n\n```sh\n# Find tasks with \"report\" in the title that are due before the end of 2025\n$ ./gtasks tasks list --title-contains \"report\" --due-before \"2025-12-31\"\n\n# Find tasks with \"meeting\" in the notes\n$ ./gtasks tasks list --notes-contains \"meeting\"\n```\n\n#### Changing the Output Format\n\nYou can change the output format to JSON or YAML, which is useful for scripting.\n\n```sh\n# Get a list of task lists in JSON format\n$ ./gtasks tasklists list --output json\n[\n  {\n    \"id\": \"MTM1NTM2MzQzNzczNDkyNzc1NTQ6MDow\",\n    \"title\": \"My tasks\",\n    ...\n  }\n]\n```\n\n## 7. Interactive Mode\n\n`gtasks` provides a full-screen interactive mode that allows you to manage your tasks in a more fluid, application-like experience.\n\nTo start the interactive mode, run the following command:\n\n```sh\n./gtasks interactive --tasklist \u003ctasklist_id\u003e\n```\n\n### Features\n\n*   **View Tasks:** See all your tasks in a list.\n*   **Add Tasks:** Press `a` to add a new task.\n*   **Edit Tasks:** Press `e` to edit the selected task.\n*   **Delete Tasks:** Press `d` to delete the selected task.\n*   **Complete/Uncomplete Tasks:** Press `space` to toggle the completion status of the selected task.\n\n### Keybindings\n\n-   `q`, `ctrl+c`: Quit the application.\n-   `up`, `k`: Move the cursor up.\n-   `down`, `j`: Move the cursor down.\n-   `a`: Add a new task.\n-   `e`: Edit the selected task.\n-   `d`: Delete the selected task.\n-   `space`: Toggle the completion status of the selected task.\n\n## 8. Error Handling\n\n`gtasks-cli` is designed to provide clear and actionable feedback when errors occur. Here's how it handles common issues:\n\n*   **Network Errors:** If the CLI cannot connect to the Google Tasks API, it will print an error message and exit. If you are offline, you can use the `--offline` flag to work with a local copy of your tasks.\n*   **Authentication Errors:** If your credentials have expired or are invalid, the CLI will prompt you to log in again.\n*   **API Errors:** If the Google Tasks API returns an error, the CLI will print the error message from the API and exit.\n*   **Not Found Errors:** If you try to access a resource that does not exist (e.g., a task or tasklist with an invalid ID), the CLI will print a \"not found\" error and exit.\n\n## 9. Implementation Details\n\n- **Language:** Go\n- **Libraries:**\n  - Cobra (`github.com/spf13/cobra`) for CLI structure.\n  - Bubble Tea (`github.com/charmbracelet/bubbletea`) for the interactive TUI.\n  - Google API Client for Go (`google.golang.org/api/tasks/v1`).\n  - Go OAuth2 Library (`golang.org/x/oauth2`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanicksenn%2Fgtasks-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyanicksenn%2Fgtasks-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanicksenn%2Fgtasks-cli/lists"}