asana-api-cli 1.3.0__tar.gz → 1.5.0__tar.gz

{asana_api_cli-1.3.0/src/asana_api_cli.egg-info → asana_api_cli-1.5.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: asana-api-cli
-Version: 1.3.0
+Version: 1.5.0
 Summary: Command-line wrapper around the official Asana Python SDK
 Author-email: Masanao Izumo <asana@masanao.site>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/izumo-m/asana-api-cli
 Project-URL: Repository, https://github.com/izumo-m/asana-api-cli
 Project-URL: Issues, https://github.com/izumo-m/asana-api-cli/issues
+Project-URL: Changelog, https://github.com/izumo-m/asana-api-cli/blob/main/CHANGELOG.md
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -65,28 +66,27 @@ and add the line to `~/.zshrc` or `~/.config/fish/config.fish` respectively.
 ## Usage
 
 ```bash
-# Show version
+# Version and help
 asana-api --version
-
-# List commands
 asana-api --help
 asana-api tasks --help
 asana-api tasks get-tasks --help
 
-# List workspaces
+# List workspaces and projects
 asana-api workspaces get-workspaces
-
-# List projects (workspace resolved from ASANA_DEFAULT_WORKSPACE)
 asana-api projects get-projects-for-workspace
 asana-api projects get-projects --workspace <WORKSPACE_GID>
 
-# List tasks (first page)
+# List tasks (first page only by default)
 asana-api tasks get-tasks --project <PROJECT_GID>
 
-# Auto-fetch all pages
-asana-api tasks get-tasks --project <PROJECT_GID> --paginate
+# Preview the first few items
+asana-api tasks get-tasks --project <PROJECT_GID> --max-items 5
+
+# Fetch every item across pages
+asana-api tasks get-tasks --project <PROJECT_GID> --all-items
 
-# Single task (--task instead of positional argument)
+# Single task
 asana-api tasks get-task --task <TASK_GID>
 
 # Create a task (body is a JSON string)
@@ -97,6 +97,9 @@ asana-api tasks get-tasks --project <PID> --output table
 asana-api tasks get-tasks --project <PID> --query '.data' --output csv
 ```
 
+See [Pagination](#pagination) for fetching across pages and
+[Global options](#global-options) for `--debug`, `--access-token`, etc.
+
 ### Workspace resolution
 
 Many API endpoints require a workspace. For those endpoints (e.g.
@@ -110,6 +113,60 @@ fallback is **not** used — pass `--workspace` explicitly if needed. This
 prevents conflicts with other scope parameters like `--project` that are
 mutually exclusive with workspace in the Asana API.
 
+## Pagination
+
+Listing endpoints (e.g. `tasks get-tasks`) return paginated results. The CLI
+provides four ways to control how much is fetched:
+
+| Option | Behavior |
+|--------|----------|
+| (none) | Fetch a single page (Asana default: 100 items) |
+| `--max-items N` | Fetch up to N items, auto-paginating across pages. The last request is automatically capped to the remaining count. |
+| `--all-items` | Fetch every page until the server reports no more |
+| `--offset <TOKEN>` | Manual pagination: pass the `next_page.offset` token from the previous response |
+
+`--max-items` and `--all-items` are mutually exclusive.
+
+`--page-size N` tunes the per-page request size (Asana API requires 1-100,
+default 100). Rarely needed — combine with `--all-items` or `--max-items` only
+when the default doesn't suit (e.g. very large rows or rate-limit tuning).
+
+```bash
+# Auto-paginate up to 250 items
+asana-api tasks get-tasks --project <PID> --max-items 250
+
+# Fetch everything
+asana-api tasks get-tasks --project <PID> --all-items
+
+# Manual pagination using the offset token
+asana-api tasks get-tasks --project <PID> --offset <TOKEN>
+```
+
+## Global options
+
+These options work at any level of the command tree, so the following are
+equivalent:
+
+```bash
+asana-api --debug tasks get-tasks --project <PID>
+asana-api tasks get-tasks --project <PID> --debug
+```
+
+When the same option is given at multiple levels, the more specific (later)
+one wins.
+
+| Option | Description |
+|--------|-------------|
+| `--access-token TOKEN` | Asana personal access token (default: `$ASANA_ACCESS_TOKEN`) |
+| `--host URL` | Override API base URL (default: `https://app.asana.com/api/1.0`) |
+| `--proxy URL` | HTTP/HTTPS proxy URL |
+| `--no-verify-ssl` | Disable TLS certificate verification (insecure) |
+| `--ca-cert PATH` | Path to a PEM bundle of trusted CA certificates |
+| `--retries N` | Number of retries on 429/5xx responses (default: 5) |
+| `--timeout SECONDS` | Per-request timeout in seconds |
+| `--temp-dir PATH` | Directory for temporary downloads |
+| `--debug` | Print HTTP request/response to stderr for troubleshooting |
+
 ## Development
 
 See [docs/development.md](https://github.com/izumo-m/asana-api-cli/blob/main/docs/development.md)

{asana_api_cli-1.3.0 → asana_api_cli-1.5.0}/README.md

@@ -47,28 +47,27 @@ and add the line to `~/.zshrc` or `~/.config/fish/config.fish` respectively.
 ## Usage
 
 ```bash
-# Show version
+# Version and help
 asana-api --version
-
-# List commands
 asana-api --help
 asana-api tasks --help
 asana-api tasks get-tasks --help
 
-# List workspaces
+# List workspaces and projects
 asana-api workspaces get-workspaces
-
-# List projects (workspace resolved from ASANA_DEFAULT_WORKSPACE)
 asana-api projects get-projects-for-workspace
 asana-api projects get-projects --workspace <WORKSPACE_GID>
 
-# List tasks (first page)
+# List tasks (first page only by default)
 asana-api tasks get-tasks --project <PROJECT_GID>
 
-# Auto-fetch all pages
-asana-api tasks get-tasks --project <PROJECT_GID> --paginate
+# Preview the first few items
+asana-api tasks get-tasks --project <PROJECT_GID> --max-items 5
+
+# Fetch every item across pages
+asana-api tasks get-tasks --project <PROJECT_GID> --all-items
 
-# Single task (--task instead of positional argument)
+# Single task
 asana-api tasks get-task --task <TASK_GID>
 
 # Create a task (body is a JSON string)
@@ -79,6 +78,9 @@ asana-api tasks get-tasks --project <PID> --output table
 asana-api tasks get-tasks --project <PID> --query '.data' --output csv
 ```
 
+See [Pagination](#pagination) for fetching across pages and
+[Global options](#global-options) for `--debug`, `--access-token`, etc.
+
 ### Workspace resolution
 
 Many API endpoints require a workspace. For those endpoints (e.g.
@@ -92,6 +94,60 @@ fallback is **not** used — pass `--workspace` explicitly if needed. This
 prevents conflicts with other scope parameters like `--project` that are
 mutually exclusive with workspace in the Asana API.
 
+## Pagination
+
+Listing endpoints (e.g. `tasks get-tasks`) return paginated results. The CLI
+provides four ways to control how much is fetched:
+
+| Option | Behavior |
+|--------|----------|
+| (none) | Fetch a single page (Asana default: 100 items) |
+| `--max-items N` | Fetch up to N items, auto-paginating across pages. The last request is automatically capped to the remaining count. |
+| `--all-items` | Fetch every page until the server reports no more |
+| `--offset <TOKEN>` | Manual pagination: pass the `next_page.offset` token from the previous response |
+
+`--max-items` and `--all-items` are mutually exclusive.
+
+`--page-size N` tunes the per-page request size (Asana API requires 1-100,
+default 100). Rarely needed — combine with `--all-items` or `--max-items` only
+when the default doesn't suit (e.g. very large rows or rate-limit tuning).
+
+```bash
+# Auto-paginate up to 250 items
+asana-api tasks get-tasks --project <PID> --max-items 250
+
+# Fetch everything
+asana-api tasks get-tasks --project <PID> --all-items
+
+# Manual pagination using the offset token
+asana-api tasks get-tasks --project <PID> --offset <TOKEN>
+```
+
+## Global options
+
+These options work at any level of the command tree, so the following are
+equivalent:
+
+```bash
+asana-api --debug tasks get-tasks --project <PID>
+asana-api tasks get-tasks --project <PID> --debug
+```
+
+When the same option is given at multiple levels, the more specific (later)
+one wins.
+
+| Option | Description |
+|--------|-------------|
+| `--access-token TOKEN` | Asana personal access token (default: `$ASANA_ACCESS_TOKEN`) |
+| `--host URL` | Override API base URL (default: `https://app.asana.com/api/1.0`) |
+| `--proxy URL` | HTTP/HTTPS proxy URL |
+| `--no-verify-ssl` | Disable TLS certificate verification (insecure) |
+| `--ca-cert PATH` | Path to a PEM bundle of trusted CA certificates |
+| `--retries N` | Number of retries on 429/5xx responses (default: 5) |
+| `--timeout SECONDS` | Per-request timeout in seconds |
+| `--temp-dir PATH` | Directory for temporary downloads |
+| `--debug` | Print HTTP request/response to stderr for troubleshooting |
+
 ## Development
 
 See [docs/development.md](https://github.com/izumo-m/asana-api-cli/blob/main/docs/development.md)

{asana_api_cli-1.3.0 → asana_api_cli-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "asana-api-cli"
-version = "1.3.0"
+version = "1.5.0"
 description = "Command-line wrapper around the official Asana Python SDK"
 authors = [{name = "Masanao Izumo", email = "asana@masanao.site"}]
 readme = "README.md"
@@ -17,6 +17,7 @@ dependencies = [
 Homepage = "https://github.com/izumo-m/asana-api-cli"
 Repository = "https://github.com/izumo-m/asana-api-cli"
 Issues = "https://github.com/izumo-m/asana-api-cli/issues"
+Changelog = "https://github.com/izumo-m/asana-api-cli/blob/main/CHANGELOG.md"
 
 [project.scripts]
 asana-api = "asana_api_cli.cli:main"
@@ -27,6 +28,7 @@ dev = [
     "pytest>=9,<10",
     "build>=1,<2",
     "twine>=6,<7",
+    "vermin>=1.6,<2",
 ]
 
 [build-system]

asana_api_cli-1.5.0/src/asana_api_cli/cli/__init__.py

@@ -0,0 +1,93 @@
+# This file is auto-generated by tools/codegen.py — do not edit manually.
+from __future__ import annotations
+
+import click
+
+from asana_api_cli.click_ext import LazyGroup
+from asana_api_cli.session import runtime
+from asana_api_cli.version import version_string
+
+
+LAZY_SUBCOMMANDS: dict[str, tuple[str, str]] = {
+    "access-requests": ("asana_api_cli.cli.access_requests:access_requests_group", "AccessRequests commands."),
+    "allocations": ("asana_api_cli.cli.allocations:allocations_group", "Allocations commands."),
+    "attachments": ("asana_api_cli.cli.attachments:attachments_group", "Attachments commands."),
+    "audit-log-api": ("asana_api_cli.cli.audit_log_api:audit_log_api_group", "AuditLogAPI commands."),
+    "batch-api": ("asana_api_cli.cli.batch_api:batch_api_group", "BatchAPI commands."),
+    "budgets": ("asana_api_cli.cli.budgets:budgets_group", "Budgets commands."),
+    "custom-field-settings": ("asana_api_cli.cli.custom_field_settings:custom_field_settings_group", "CustomFieldSettings commands."),
+    "custom-fields": ("asana_api_cli.cli.custom_fields:custom_fields_group", "CustomFields commands."),
+    "custom-types": ("asana_api_cli.cli.custom_types:custom_types_group", "CustomTypes commands."),
+    "events": ("asana_api_cli.cli.events:events_group", "Events commands."),
+    "exports": ("asana_api_cli.cli.exports:exports_group", "Exports commands."),
+    "goal-relationships": ("asana_api_cli.cli.goal_relationships:goal_relationships_group", "GoalRelationships commands."),
+    "goals": ("asana_api_cli.cli.goals:goals_group", "Goals commands."),
+    "jobs": ("asana_api_cli.cli.jobs:jobs_group", "Jobs commands."),
+    "memberships": ("asana_api_cli.cli.memberships:memberships_group", "Memberships commands."),
+    "organization-exports": ("asana_api_cli.cli.organization_exports:organization_exports_group", "OrganizationExports commands."),
+    "portfolio-memberships": ("asana_api_cli.cli.portfolio_memberships:portfolio_memberships_group", "PortfolioMemberships commands."),
+    "portfolios": ("asana_api_cli.cli.portfolios:portfolios_group", "Portfolios commands."),
+    "project-briefs": ("asana_api_cli.cli.project_briefs:project_briefs_group", "ProjectBriefs commands."),
+    "project-memberships": ("asana_api_cli.cli.project_memberships:project_memberships_group", "ProjectMemberships commands."),
+    "project-portfolio-settings": ("asana_api_cli.cli.project_portfolio_settings:project_portfolio_settings_group", "ProjectPortfolioSettings commands."),
+    "project-statuses": ("asana_api_cli.cli.project_statuses:project_statuses_group", "ProjectStatuses commands."),
+    "project-templates": ("asana_api_cli.cli.project_templates:project_templates_group", "ProjectTemplates commands."),
+    "projects": ("asana_api_cli.cli.projects:projects_group", "Projects commands."),
+    "rates": ("asana_api_cli.cli.rates:rates_group", "Rates commands."),
+    "reactions": ("asana_api_cli.cli.reactions:reactions_group", "Reactions commands."),
+    "roles": ("asana_api_cli.cli.roles:roles_group", "Roles commands."),
+    "rules": ("asana_api_cli.cli.rules:rules_group", "Rules commands."),
+    "sections": ("asana_api_cli.cli.sections:sections_group", "Sections commands."),
+    "status-updates": ("asana_api_cli.cli.status_updates:status_updates_group", "StatusUpdates commands."),
+    "stories": ("asana_api_cli.cli.stories:stories_group", "Stories commands."),
+    "tags": ("asana_api_cli.cli.tags:tags_group", "Tags commands."),
+    "task-templates": ("asana_api_cli.cli.task_templates:task_templates_group", "TaskTemplates commands."),
+    "tasks": ("asana_api_cli.cli.tasks:tasks_group", "Tasks commands."),
+    "team-memberships": ("asana_api_cli.cli.team_memberships:team_memberships_group", "TeamMemberships commands."),
+    "teams": ("asana_api_cli.cli.teams:teams_group", "Teams commands."),
+    "time-periods": ("asana_api_cli.cli.time_periods:time_periods_group", "TimePeriods commands."),
+    "time-tracking-categories": ("asana_api_cli.cli.time_tracking_categories:time_tracking_categories_group", "TimeTrackingCategories commands."),
+    "time-tracking-entries": ("asana_api_cli.cli.time_tracking_entries:time_tracking_entries_group", "TimeTrackingEntries commands."),
+    "timesheet-approval-statuses": ("asana_api_cli.cli.timesheet_approval_statuses:timesheet_approval_statuses_group", "TimesheetApprovalStatuses commands."),
+    "typeahead": ("asana_api_cli.cli.typeahead:typeahead_group", "Typeahead commands."),
+    "user-task-lists": ("asana_api_cli.cli.user_task_lists:user_task_lists_group", "UserTaskLists commands."),
+    "users": ("asana_api_cli.cli.users:users_group", "Users commands."),
+    "webhooks": ("asana_api_cli.cli.webhooks:webhooks_group", "Webhooks commands."),
+    "workspace-memberships": ("asana_api_cli.cli.workspace_memberships:workspace_memberships_group", "WorkspaceMemberships commands."),
+    "workspaces": ("asana_api_cli.cli.workspaces:workspaces_group", "Workspaces commands."),
+}
+
+
+@click.group(cls=LazyGroup, lazy_subcommands=LAZY_SUBCOMMANDS)
+@click.version_option(version_string(), prog_name="asana-api")
+@click.option("--host", default=None, help="Override API base URL (default: https://app.asana.com/api/1.0)")
+@click.option("--proxy", default=None, help="HTTP/HTTPS proxy URL")
+@click.option("--no-verify-ssl", is_flag=True, default=False, help="Disable TLS certificate verification (insecure)")
+@click.option("--ca-cert", "ca_cert", default=None, type=click.Path(exists=True, dir_okay=False), help="Path to a PEM bundle of trusted CA certificates")
+@click.option("--retries", type=int, default=None, help="Number of retries on 429/5xx responses (default: 5)")
+@click.option("--timeout", type=float, default=None, help="Per-request timeout in seconds")
+@click.option("--access-token", "access_token", default=None, help="Asana personal access token (default: $ASANA_ACCESS_TOKEN)")
+@click.option("--temp-dir", "temp_dir", default=None, type=click.Path(file_okay=False), help="Directory for temporary downloads")
+@click.option("--debug", is_flag=True, default=False, help="Print HTTP request/response to stderr for troubleshooting")
+def main(
+    host: str | None,
+    proxy: str | None,
+    no_verify_ssl: bool,
+    ca_cert: str | None,
+    retries: int | None,
+    timeout: float | None,
+    access_token: str | None,
+    temp_dir: str | None,
+    debug: bool,
+) -> None:
+    """Asana API CLI (SDK-backed wrapper)."""
+    runtime.host = host
+    runtime.proxy = proxy
+    runtime.verify_ssl = not no_verify_ssl
+    runtime.ssl_ca_cert = ca_cert
+    runtime.retries = retries
+    runtime.timeout = timeout
+    if access_token:
+        runtime.access_token = access_token
+    runtime.temp_dir = temp_dir
+    runtime.debug = debug

{asana_api_cli-1.3.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/access_requests.py

@@ -6,11 +6,12 @@ from typing import Any
 import click
 from asana import AccessRequestsApi
 
+from asana_api_cli.click_ext import GroupWithGlobalOptions
 from asana_api_cli.formatter import formatted
 from asana_api_cli.session import AsanaSession, resolve_body, resolve_workspace
 
 
-@click.group("access-requests")
+@click.group("access-requests", cls=GroupWithGlobalOptions)
 def access_requests_group() -> None:
     """AccessRequests commands."""
 

{asana_api_cli-1.3.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/allocations.py

@@ -6,11 +6,12 @@ from typing import Any
 import click
 from asana import AllocationsApi
 
+from asana_api_cli.click_ext import GroupWithGlobalOptions
 from asana_api_cli.formatter import formatted
 from asana_api_cli.session import AsanaSession, resolve_body, resolve_workspace
 
 
-@click.group("allocations")
+@click.group("allocations", cls=GroupWithGlobalOptions)
 def allocations_group() -> None:
     """Allocations commands."""
 
@@ -58,22 +59,30 @@ def get_allocation(allocation: str, opt_fields: str | None) -> Any:
 @allocations_group.command("get-allocations")
 @click.option("--workspace", default=None, help="Workspace GID (falls back to ASANA_DEFAULT_WORKSPACE)")
 @click.option("--assignee", default=None, help="Globally unique identifier for the user or placeholder the allocation is assigned to.")
-@click.option("--limit", type=int, default=None, help="Results per page. The number of objects to return per page. The value must be between 1 and 100.")
 @click.option("--offset", default=None, help="Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not pass...")
 @click.option("--opt-fields", default=None, help="This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to in...")
 @click.option("--parent", default=None, help="Globally unique identifier for the project to filter allocations by.")
-@click.option("--paginate", is_flag=True, default=False, help="Fetch all pages")
+@click.option("--all-items", "all_items", is_flag=True, default=False, help="Fetch all items (no cap)")
+@click.option("--paginate", "paginate", is_flag=True, default=False, help="(Deprecated) Alias for --all-items")
+@click.option("--page-size", "page_size", type=int, default=None, help="Items per page (Asana API requires 1-100, default 100)")
+@click.option("--max-items", "max_items", type=int, default=None, help="Stop after fetching this many items in total")
 @formatted
-def get_allocations(workspace: str | None, assignee: str | None, limit: int | None, offset: str | None, opt_fields: str | None, parent: str | None, paginate: bool) -> Any:
+def get_allocations(workspace: str | None, assignee: str | None, offset: str | None, opt_fields: str | None, parent: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get multiple allocations"""
     resolved_workspace = resolve_workspace(workspace, required=False)
-    session = AsanaSession.from_env(paginate=paginate)
+    if paginate:
+        click.echo("Warning: --paginate is deprecated; use --all-items instead.", err=True)
+    fetch_all = all_items or paginate
+    if fetch_all and max_items is not None:
+        raise click.UsageError("--max-items cannot be combined with --all-items (or its deprecated alias --paginate)")
+    effective_page_size = page_size
+    if max_items is not None and (page_size is None or page_size > max_items):
+        effective_page_size = max_items
+    session = AsanaSession.from_env(paginate=fetch_all, page_size=effective_page_size)
     api = AllocationsApi(session.client)
     opts: dict[str, Any] = {}
     if assignee is not None:
         opts["assignee"] = assignee
-    if limit is not None:
-        opts["limit"] = limit
     if offset is not None:
         opts["offset"] = offset
     if opt_fields is not None:
@@ -82,6 +91,8 @@ def get_allocations(workspace: str | None, assignee: str | None, limit: int | No
         opts["parent"] = parent
     if resolved_workspace is not None:
         opts["workspace"] = resolved_workspace
+    if max_items is not None:
+        return session.fetch_capped(api.get_allocations, opts=opts, max_items=max_items)
     return api.get_allocations(opts)
 
 

{asana_api_cli-1.3.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/attachments.py

@@ -6,11 +6,12 @@ from typing import Any
 import click
 from asana import AttachmentsApi
 
+from asana_api_cli.click_ext import GroupWithGlobalOptions
 from asana_api_cli.formatter import formatted
 from asana_api_cli.session import AsanaSession, resolve_body, resolve_workspace
 
 
-@click.group("attachments")
+@click.group("attachments", cls=GroupWithGlobalOptions)
 def attachments_group() -> None:
     """Attachments commands."""
 
@@ -73,20 +74,30 @@ def get_attachment(attachment: str, opt_fields: str | None) -> Any:
 
 @attachments_group.command("get-attachments-for-object")
 @click.option("--parent", required=True, help="Globally unique identifier for object to fetch statuses from. Must be a GID for a `project`, `project_brief`, or `task`.")
-@click.option("--limit", type=int, default=None, help="Results per page. The number of objects to return per page. The value must be between 1 and 100.")
 @click.option("--offset", default=None, help="Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not pass...")
 @click.option("--opt-fields", default=None, help="This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to in...")
-@click.option("--paginate", is_flag=True, default=False, help="Fetch all pages")
+@click.option("--all-items", "all_items", is_flag=True, default=False, help="Fetch all items (no cap)")
+@click.option("--paginate", "paginate", is_flag=True, default=False, help="(Deprecated) Alias for --all-items")
+@click.option("--page-size", "page_size", type=int, default=None, help="Items per page (Asana API requires 1-100, default 100)")
+@click.option("--max-items", "max_items", type=int, default=None, help="Stop after fetching this many items in total")
 @formatted
-def get_attachments_for_object(parent: str, limit: int | None, offset: str | None, opt_fields: str | None, paginate: bool) -> Any:
+def get_attachments_for_object(parent: str, offset: str | None, opt_fields: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get attachments from an object"""
-    session = AsanaSession.from_env(paginate=paginate)
+    if paginate:
+        click.echo("Warning: --paginate is deprecated; use --all-items instead.", err=True)
+    fetch_all = all_items or paginate
+    if fetch_all and max_items is not None:
+        raise click.UsageError("--max-items cannot be combined with --all-items (or its deprecated alias --paginate)")
+    effective_page_size = page_size
+    if max_items is not None and (page_size is None or page_size > max_items):
+        effective_page_size = max_items
+    session = AsanaSession.from_env(paginate=fetch_all, page_size=effective_page_size)
     api = AttachmentsApi(session.client)
     opts: dict[str, Any] = {}
-    if limit is not None:
-        opts["limit"] = limit
     if offset is not None:
         opts["offset"] = offset
     if opt_fields is not None:
         opts["opt_fields"] = opt_fields
+    if max_items is not None:
+        return session.fetch_capped(api.get_attachments_for_object, parent, opts=opts, max_items=max_items)
     return api.get_attachments_for_object(parent, opts)

{asana_api_cli-1.3.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/audit_log_api.py

@@ -6,11 +6,12 @@ from typing import Any
 import click
 from asana import AuditLogAPIApi
 
+from asana_api_cli.click_ext import GroupWithGlobalOptions
 from asana_api_cli.formatter import formatted
 from asana_api_cli.session import AsanaSession, resolve_body, resolve_workspace
 
 
-@click.group("audit-log-api")
+@click.group("audit-log-api", cls=GroupWithGlobalOptions)
 def audit_log_api_group() -> None:
     """AuditLogAPI commands."""
 
@@ -21,16 +22,26 @@ def audit_log_api_group() -> None:
 @click.option("--actor-type", default=None, help="Filter to events with an actor of this type. This only needs to be included if querying for actor types without an ID. If `actor_gid` is included, this should be excluded.")
 @click.option("--end-at", default=None, help="Filter to events created before this time (exclusive).")
 @click.option("--event-type", default=None, help="Filter to events of this type. Refer to the [supported audit log events](/docs/audit-log-events#supported-audit-log-events) for a full list of values.")
-@click.option("--limit", type=int, default=None, help="Results per page. The number of objects to return per page. The value must be between 1 and 100.")
 @click.option("--offset", default=None, help="Offset token. An offset to the next page returned by the API. A pagination request will return an offset token, which can be used as an input parameter to the next request. If an offset is not pass...")
 @click.option("--resource-gid", default=None, help="Filter to events with this resource ID.")
 @click.option("--start-at", default=None, help="Filter to events created after this time (inclusive).")
-@click.option("--paginate", is_flag=True, default=False, help="Fetch all pages")
+@click.option("--all-items", "all_items", is_flag=True, default=False, help="Fetch all items (no cap)")
+@click.option("--paginate", "paginate", is_flag=True, default=False, help="(Deprecated) Alias for --all-items")
+@click.option("--page-size", "page_size", type=int, default=None, help="Items per page (Asana API requires 1-100, default 100)")
+@click.option("--max-items", "max_items", type=int, default=None, help="Stop after fetching this many items in total")
 @formatted
-def get_audit_log_events(workspace: str | None, actor_gid: str | None, actor_type: str | None, end_at: str | None, event_type: str | None, limit: int | None, offset: str | None, resource_gid: str | None, start_at: str | None, paginate: bool) -> Any:
+def get_audit_log_events(workspace: str | None, actor_gid: str | None, actor_type: str | None, end_at: str | None, event_type: str | None, offset: str | None, resource_gid: str | None, start_at: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get audit log events"""
     resolved_workspace = resolve_workspace(workspace, required=True)
-    session = AsanaSession.from_env(paginate=paginate)
+    if paginate:
+        click.echo("Warning: --paginate is deprecated; use --all-items instead.", err=True)
+    fetch_all = all_items or paginate
+    if fetch_all and max_items is not None:
+        raise click.UsageError("--max-items cannot be combined with --all-items (or its deprecated alias --paginate)")
+    effective_page_size = page_size
+    if max_items is not None and (page_size is None or page_size > max_items):
+        effective_page_size = max_items
+    session = AsanaSession.from_env(paginate=fetch_all, page_size=effective_page_size)
     api = AuditLogAPIApi(session.client)
     opts: dict[str, Any] = {}
     if actor_gid is not None:
@@ -41,12 +52,12 @@ def get_audit_log_events(workspace: str | None, actor_gid: str | None, actor_typ
         opts["end_at"] = end_at
     if event_type is not None:
         opts["event_type"] = event_type
-    if limit is not None:
-        opts["limit"] = limit
     if offset is not None:
         opts["offset"] = offset
     if resource_gid is not None:
         opts["resource_gid"] = resource_gid
     if start_at is not None:
         opts["start_at"] = start_at
+    if max_items is not None:
+        return session.fetch_capped(api.get_audit_log_events, resolved_workspace, opts=opts, max_items=max_items)
     return api.get_audit_log_events(resolved_workspace, opts)

{asana_api_cli-1.3.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/batch_api.py

@@ -6,11 +6,12 @@ from typing import Any
 import click
 from asana import BatchAPIApi
 
+from asana_api_cli.click_ext import GroupWithGlobalOptions
 from asana_api_cli.formatter import formatted
 from asana_api_cli.session import AsanaSession, resolve_body, resolve_workspace
 
 
-@click.group("batch-api")
+@click.group("batch-api", cls=GroupWithGlobalOptions)
 def batch_api_group() -> None:
     """BatchAPI commands."""
 

{asana_api_cli-1.3.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/budgets.py

@@ -6,11 +6,12 @@ from typing import Any
 import click
 from asana import BudgetsApi
 
+from asana_api_cli.click_ext import GroupWithGlobalOptions
 from asana_api_cli.formatter import formatted
 from asana_api_cli.session import AsanaSession, resolve_body, resolve_workspace
 
 
-@click.group("budgets")
+@click.group("budgets", cls=GroupWithGlobalOptions)
 def budgets_group() -> None:
     """Budgets commands."""