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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asana-api-cli
-Version: 1.4.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
@@ -66,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)
@@ -98,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.
@@ -111,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.4.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.4.0 → asana_api_cli-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "asana-api-cli"
-version = "1.4.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"
@@ -28,6 +28,7 @@ dev = [
     "pytest>=9,<10",
     "build>=1,<2",
     "twine>=6,<7",
+    "vermin>=1.6,<2",
 ]
 
 [build-system]

{asana_api_cli-1.4.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/__init__.py

@@ -64,7 +64,6 @@ LAZY_SUBCOMMANDS: dict[str, tuple[str, str]] = {
 @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("--page-limit", "page_limit", type=int, default=None, help="Default per-page size for paginated endpoints")
 @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)")
@@ -75,7 +74,6 @@ def main(
     proxy: str | None,
     no_verify_ssl: bool,
     ca_cert: str | None,
-    page_limit: int | None,
     retries: int | None,
     timeout: float | None,
     access_token: str | None,
@@ -87,7 +85,6 @@ def main(
     runtime.proxy = proxy
     runtime.verify_ssl = not no_verify_ssl
     runtime.ssl_ca_cert = ca_cert
-    runtime.page_limit = page_limit
     runtime.retries = retries
     runtime.timeout = timeout
     if access_token:

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

@@ -59,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:
@@ -83,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.4.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/attachments.py

@@ -74,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.4.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/audit_log_api.py

@@ -22,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:
@@ -42,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.4.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/custom_field_settings.py

@@ -18,64 +18,94 @@ def custom_field_settings_group() -> None:
 
 @custom_field_settings_group.command("get-custom-field-settings-for-goal")
 @click.option("--goal", required=True, help="Globally unique identifier for the goal.")
-@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_custom_field_settings_for_goal(goal: str, limit: int | None, offset: str | None, opt_fields: str | None, paginate: bool) -> Any:
+def get_custom_field_settings_for_goal(goal: str, offset: str | None, opt_fields: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get a goal's custom fields"""
-    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 = CustomFieldSettingsApi(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_custom_field_settings_for_goal, goal, opts=opts, max_items=max_items)
     return api.get_custom_field_settings_for_goal(goal, opts)
 
 
 @custom_field_settings_group.command("get-custom-field-settings-for-portfolio")
 @click.option("--portfolio", required=True, help="Globally unique identifier for the portfolio.")
-@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_custom_field_settings_for_portfolio(portfolio: str, limit: int | None, offset: str | None, opt_fields: str | None, paginate: bool) -> Any:
+def get_custom_field_settings_for_portfolio(portfolio: str, offset: str | None, opt_fields: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get a portfolio's custom fields"""
-    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 = CustomFieldSettingsApi(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_custom_field_settings_for_portfolio, portfolio, opts=opts, max_items=max_items)
     return api.get_custom_field_settings_for_portfolio(portfolio, opts)
 
 
 @custom_field_settings_group.command("get-custom-field-settings-for-project")
 @click.option("--project", required=True, help="Globally unique identifier for the project.")
-@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_custom_field_settings_for_project(project: str, limit: int | None, offset: str | None, opt_fields: str | None, paginate: bool) -> Any:
+def get_custom_field_settings_for_project(project: str, offset: str | None, opt_fields: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get a project's custom fields"""
-    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 = CustomFieldSettingsApi(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_custom_field_settings_for_project, project, opts=opts, max_items=max_items)
     return api.get_custom_field_settings_for_project(project, opts)
 
 

{asana_api_cli-1.4.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/custom_fields.py

@@ -72,23 +72,33 @@ def get_custom_field(custom_field: str, opt_fields: str | None) -> Any:
 
 @custom_fields_group.command("get-custom-fields-for-workspace")
 @click.option("--workspace", default=None, help="Workspace GID (falls back to ASANA_DEFAULT_WORKSPACE)")
-@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_custom_fields_for_workspace(workspace: str | None, limit: int | None, offset: str | None, opt_fields: str | None, paginate: bool) -> Any:
+def get_custom_fields_for_workspace(workspace: str | None, offset: str | None, opt_fields: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get a workspace's custom fields"""
     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 = CustomFieldsApi(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_custom_fields_for_workspace, resolved_workspace, opts=opts, max_items=max_items)
     return api.get_custom_fields_for_workspace(resolved_workspace, opts)
 
 

{asana_api_cli-1.4.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/custom_types.py

@@ -32,20 +32,30 @@ def get_custom_type(custom_type: str, opt_fields: str | None) -> Any:
 
 @custom_types_group.command("get-custom-types")
 @click.option("--project", required=True, help="Globally unique identifier for the project, which is used as a filter when retrieving all custom types.")
-@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_custom_types(project: str, limit: int | None, offset: str | None, opt_fields: str | None, paginate: bool) -> Any:
+def get_custom_types(project: str, offset: str | None, opt_fields: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get all custom types associated with 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 = CustomTypesApi(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_custom_types, project, opts=opts, max_items=max_items)
     return api.get_custom_types(project, opts)

{asana_api_cli-1.4.0 → asana_api_cli-1.5.0}/src/asana_api_cli/cli/goal_relationships.py

@@ -48,25 +48,35 @@ def get_goal_relationship(goal_relationship: str, opt_fields: str | None) -> Any
 
 @goal_relationships_group.command("get-goal-relationships")
 @click.option("--supported-goal", required=True, help="Globally unique identifier for the supported goal in the goal relationship.")
-@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("--resource-subtype", default=None, help="If provided, filter to goal relationships with a given resource_subtype.")
-@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_goal_relationships(supported_goal: str, limit: int | None, offset: str | None, opt_fields: str | None, resource_subtype: str | None, paginate: bool) -> Any:
+def get_goal_relationships(supported_goal: str, offset: str | None, opt_fields: str | None, resource_subtype: str | None, all_items: bool, paginate: bool, page_size: int | None, max_items: int | None) -> Any:
     """Get goal relationships"""
-    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 = GoalRelationshipsApi(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 resource_subtype is not None:
         opts["resource_subtype"] = resource_subtype
+    if max_items is not None:
+        return session.fetch_capped(api.get_goal_relationships, supported_goal, opts=opts, max_items=max_items)
     return api.get_goal_relationships(supported_goal, opts)