@togglhq/cli 1.5.19

package/README.md

@@ -0,0 +1,299 @@
+# @toggl/cli
+
+Command-line interface for [Toggl Focus](https://focus.toggl.com). Published publicly as **`@togglhq/cli`** on **npmjs.org**. Internal builds publish as **`@toggl/cli-internal`** on GitHub Packages.
+
+## Installation
+
+From npm (no GitHub token):
+
+```bash
+npm install -g @togglhq/cli
+```
+
+Or from GitHub Packages (Toggl staff): configure your `.npmrc` with a GitHub Packages token, then:
+
+```bash
+npm install -g @toggl/cli-internal
+```
+
+Or run without installing:
+
+```bash
+npx @togglhq/cli
+```
+
+## Authentication
+
+```bash
+toggl auth
+```
+
+Opens a browser for OAuth sign-in. On success, credentials are saved to `~/.toggl/focus-tools.json`. When `--profile` is omitted, the CLI saves the account under a name based on your account, such as `hazem-12345`, and makes it active.
+
+**Options:**
+
+| Flag                  | Description                                                           |
+| --------------------- | --------------------------------------------------------------------- |
+| `--workspace-id <id>` | Select a specific workspace (required when your account has multiple) |
+| `--profile <name>`    | Save credentials under an explicit profile name                       |
+
+Sessions refresh automatically. Re-run `toggl auth` only to switch workspaces or after 4 weeks of inactivity.
+
+## Profiles
+
+Use profiles to switch between saved accounts and environments:
+
+```bash
+toggl profile list
+toggl profile current
+toggl profile switch hazem-12345
+toggl profile switch   # omit name in a TTY: pick from a menu or use the only profile
+toggl profile remove hazem-12345
+```
+
+The active profile controls both the account and environment for later commands. You can still override it for one call with the global `--profile <name>` flag.
+
+## Agent skill setup
+
+`@toggl/cli` ships a `toggl-cli` agent skill under `skills/toggl-cli`. Install it with:
+
+```bash
+toggl skill setup
+```
+
+This delegates to the [`skills`](https://www.npmjs.com/package/skills) CLI, listed as a **dependency** of `@toggl/cli` (no separate install). Interactive agent/scope prompts come from that CLI.
+
+After upgrading the CLI, refresh the skill install:
+
+```bash
+toggl skill sync
+```
+
+By default the installer **symlinks** into your agent skill dirs so updates track CLI upgrades; use `--copy` only if you need a detached snapshot (then re-run `toggl skill sync` after upgrades). Pass flags for non-interactive setup:
+
+```bash
+toggl skill setup --agent cursor --global --copy --yes
+toggl skill setup --agent cursor codex --copy --yes
+```
+
+## Command shape
+
+Generated Focus commands look like:
+
+```
+toggl [global flags] <group> … <subcommand> [flags]
+```
+
+Many endpoints use two segments (`toggl tasks list`). Some use nested groups, including:
+
+- **`toggl organization …`** — organization APIs (not `toggl org …`; there is no `org` top-level command). Examples: `toggl organization invitations list`, `toggl organization members get`, `toggl organization workspaces list`.
+- **`toggl shared …`** — shared workspace/org data routed through `@toggl/queries` helpers (status, holidays, working hours, time off). Example: `toggl shared status get`.
+
+Core resource groups still include `tasks`, `projects`, `time-blocks`, `time-entries`, `statuses`, `users`, `tags`, `clients`, and others surfaced by `@toggl/operations`. Endpoints marked **`hidden: true`** in the catalog (currently calendar-integration and scheduler helper operations) are omitted from the CLI and MCP. Existing public command paths and operation IDs stay stable; use `toggl --help` and `toggl <group> --help` to explore what shipped.
+
+**Typical entity commands:**
+
+| Resource       | Actions                                                  |
+| -------------- | -------------------------------------------------------- |
+| `tasks`        | `list` (alias `ls`), `get`, `create`, `update`, `delete` |
+| `projects`     | `list` (alias `ls`), `get`, `create`, `update`, `delete` |
+| `time-blocks`  | `list` (alias `ls`), `get`, `create`, `update`, `delete` |
+| `time-entries` | `list` (alias `ls`), `start`, `stop`                     |
+| `statuses`     | `list` (alias `ls`)                                      |
+| `users`        | `list` (alias `ls`)                                      |
+
+Bulk mutations use `toggl <resource> bulk <verb>`; see `toggl tasks bulk --help`.
+
+**Global flags** (placed before the command path):
+
+| Flag                  | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| `--json`              | Pretty-printed JSON output (easier to pipe than human tables) |
+| `--workspace-id <id>` | Override the active workspace for this call                   |
+| `--profile <name>`    | Use a named auth profile                                      |
+
+**Per-command flags** on generated operations always include `--data`, `--data-file`, and `--dry-run`. **`--interactive`** / **`--no-interactive`** appear only when the operation’s catalog metadata allows interactive prompting (read-only operations default to non-interactive unless marked otherwise). Interactive prompting requires a TTY and is disabled when you pass `--json`, `--data`, `--data-file`, `CI`, or `TOGGL_NON_INTERACTIVE`.
+
+To see scalar flags for an operation, use **`toggl <group> … <command> --help`**. To print the resolved operation id and validated body without calling the API, use **`--dry-run`**.
+
+## Providing input
+
+There are three ways to pass the request body:
+
+### 1. Scalar flags
+
+Each input field maps to a `--field-name` flag. Numeric values are coerced automatically.
+
+```bash
+toggl tasks get --task-id 12345
+toggl tasks list --project-id 999 --status-id 243956
+toggl time-entries list --date-from 2025-01-01 --date-to 2025-01-07
+toggl time-entries start --task-id 12345 --type activity
+```
+
+For `update` commands, payload fields use a `--payload-<field>` prefix:
+
+```bash
+toggl tasks update --task-id 12345 --payload-name "New name" --payload-status-id 270002
+toggl projects update --project-id 999 --payload-name "Renamed"
+```
+
+### 2. `--data` inline JSON
+
+Pass the full input as a JSON string:
+
+```bash
+toggl tasks list --data '{"project_id": 436195, "per_page": 50}'
+toggl tasks create --data '{"name": "Fix login bug", "project_id": 436195}'
+toggl tasks update --data '{"task_id": 12345, "payload": {"name": "Updated", "status_id": 270002}}'
+```
+
+### 3. `--data -` (stdin) or `--data-file <path>`
+
+Read JSON from stdin or a file:
+
+```bash
+echo '{"task_id": 12345}' | toggl tasks get --data -
+toggl tasks create --data-file ./new-task.json
+```
+
+## Output and errors
+
+- Successful output goes to **stdout** as JSON (pretty-printed; `--json` keeps JSON while skipping human-oriented formatting helpers).
+- Validation errors and API errors go to **stderr**.
+- Exit code `0` on success, `1` on error.
+
+## Safety flags
+
+### `--dry-run`
+
+Preview the resolved input without making an API call. Output includes `dry_run: true`, the operation ID, and the validated input object:
+
+```bash
+toggl tasks delete --task-id 12345 --dry-run
+# {"dry_run":true,"operation":"focus.tasks.delete","input":{"task_id":12345}}
+```
+
+### `--yes` (destructive operations)
+
+`delete` commands require `--yes` to execute. Omitting it prints an error to stderr:
+
+```bash
+toggl tasks delete --task-id 12345 --yes
+toggl projects delete --project-id 999 --yes
+toggl time-blocks delete --task-id 12345 --time-block-id 67890 --yes
+```
+
+## Examples
+
+**Tasks**
+
+```bash
+# List all tasks in a project
+toggl tasks list --project-id 436195
+
+# Get a single task
+toggl tasks get --task-id 12345
+
+# Create a task
+toggl tasks create --data '{"name": "Write release notes", "project_id": 436195}'
+
+# Move task to "In Progress"
+toggl tasks update --task-id 12345 --payload-status-id 270002
+
+# Delete a task (requires --yes)
+toggl tasks delete --task-id 12345 --yes
+```
+
+**Projects**
+
+```bash
+toggl projects list
+toggl projects get --project-id 436195
+toggl projects create --data '{"name": "Q3 Planning", "workspace_id": 356965}'
+toggl projects update --project-id 436195 --payload-name "Q3 Planning (archived)"
+toggl projects delete --project-id 999 --yes
+```
+
+**Time entries**
+
+```bash
+# List time entries for a week
+toggl time-entries list --date-from 2025-01-01 --date-to 2025-01-07
+
+# Start tracking (defaults type to 'activity')
+toggl time-entries start --task-id 12345
+
+# Start a break
+toggl time-entries start --type break
+
+# Stop the running timer
+toggl time-entries stop
+```
+
+**Time blocks**
+
+```bash
+# List scheduled blocks for a week
+toggl time-blocks list --date-from 2025-01-01 --date-to 2025-01-07
+
+# Create a time block
+toggl time-blocks create --data '{
+  "task_id": 12345,
+  "payload": {"start": "2025-01-06T09:00:00Z", "end": "2025-01-06T11:00:00Z"}
+}'
+
+# Delete a time block
+toggl time-blocks delete --task-id 12345 --time-block-id 67890 --yes
+```
+
+**Reference data**
+
+```bash
+# List workspace statuses (useful for getting status IDs)
+toggl statuses list
+
+# List workspace members (useful for getting user IDs)
+toggl users list
+```
+
+## Dates
+
+`--date-from` and `--date-to` accept:
+
+- `YYYY-MM-DD` — expanded to `T00:00:00Z` (from) or `T23:59:59Z` (to)
+- RFC 3339 datetime — used as-is (e.g. `2025-01-01T08:00:00+02:00`)
+
+## Troubleshooting
+
+**Not authenticated**
+
+```
+Not authenticated. Run `toggl auth` to sign in.
+```
+
+Run `toggl auth`. Credentials are stored in `~/.toggl/focus-tools.json`. If you previously authenticated with an older version, your session at `~/.toggl-focus-mcp/config.json` is still read automatically.
+
+**Invalid JSON from `--data`**
+
+```
+Invalid JSON from --data: Unexpected token ...
+```
+
+Verify your JSON is well-formed. Use `--data-file` with a file if quoting is difficult in your shell.
+
+**Validation error**
+
+```
+Invalid input: date_from: must be YYYY-MM-DD or RFC3339 datetime
+```
+
+Check field names and types. Use `--dry-run` to validate input without executing.
+
+**Debug API responses**
+
+```bash
+TOGGL_DEBUG=1 toggl tasks list
+```
+
+Prints schema validation warnings from API responses to stderr.

package/build/index.d.ts

@@ -0,0 +1 @@
+export { };

package/build/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { n as CommanderError, t as createProgram } from "./program-BwnVUFVS.js";
+//#region src/index.ts
+try {
+	await createProgram({ enableUpdateNotification: true }).parseAsync(process.argv);
+} catch (error) {
+	if (error instanceof CommanderError) process.exit(error.exitCode);
+	throw error;
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=index.js.map