Merge branch 'develop' for 3.3.0 release

Author: Masanao Izumo

CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [3.3.0] - 2026-06-29
+
+### Added
+
+- **`agents` and `ooo-entries` command groups**, picked up from the
+  `python-asana` 5.2.5 release. `agents` reads a workspace's AI agents (Asana's
+  AI Teammates): `get-agent`, `get-agents-for-workspace`. `ooo-entries` is full
+  CRUD over a user's out-of-office entries: `create-ooo-entry`,
+  `get-ooo-entries`, `get-ooo-entry`, `update-ooo-entry`, `delete-ooo-entry`.
+  The command tree is built by introspecting the installed SDK, so these appear
+  automatically when `python-asana >= 5.2.5` is installed.
+
+### Fixed
+
+- **`--set-default-header` given at more than one point in the command path no
+  longer drops the earlier headers.** A header set before the command path (for
+  example on the root) is now merged with one set after it, per header, with the
+  later occurrence winning on a name collision — the same "the later occurrence
+  wins when repeated" rule the other global options follow. Previously a second
+  `--set-default-header` at a different level replaced the whole set, silently
+  discarding the first.
+
 ## [3.2.0] - 2026-06-14
 
 ### Added
@@ -421,7 +445,8 @@ Combining a deprecated alias with its replacement (e.g.
 
 - Initial release.
 
-[Unreleased]: https://github.com/izumo-m/asana-api-cli/compare/v3.2.0...HEAD
+[Unreleased]: https://github.com/izumo-m/asana-api-cli/compare/v3.3.0...HEAD
+[3.3.0]: https://github.com/izumo-m/asana-api-cli/compare/v3.2.0...v3.3.0
 [3.2.0]: https://github.com/izumo-m/asana-api-cli/compare/v3.1.3...v3.2.0
 [3.1.3]: https://github.com/izumo-m/asana-api-cli/compare/v3.1.2...v3.1.3
 [3.1.2]: https://github.com/izumo-m/asana-api-cli/compare/v3.1.1...v3.1.2

README.md

@@ -107,7 +107,9 @@ automatically.
 
 The token can be issued from the
 [Asana Developer Console](https://app.asana.com/0/developer-console).
-No token is needed for `--help` or argument validation errors.
+No token is needed for `--help` or command-line parsing errors. (A `--query`
+jq filter is validated against the response, so it surfaces errors only after
+the API call — which does need a token.)
 
 ```bash
 export ASANA_ACCESS_TOKEN="2/12345..."

docs/api-groups.md

@@ -33,6 +33,7 @@ CRUD coverage — SDK methods are the ground truth.
 | CLI group                     | Asana reference                                                                                       | Short description (`--help`)               |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------ |
 | `access-requests`             | [Access Requests](https://developers.asana.com/reference/access-requests)                             | Manage private-object access requests      |
+| `agents`                      | [Agents](https://developers.asana.com/reference/agents)                                               | Read workspace AI agents (AI Teammates)    |
 | `allocations`                 | [Allocations](https://developers.asana.com/reference/allocations)                                     | Manage user allocations across projects    |
 | `attachments`                 | [Attachments](https://developers.asana.com/reference/attachments)                                     | Upload, list, and remove file attachments  |
 | `audit-log-api`               | [Audit Log API](https://developers.asana.com/reference/audit-log-api)                                 | Read domain audit log events               |
@@ -47,6 +48,7 @@ CRUD coverage — SDK methods are the ground truth.
 | `goals`                       | [Goals](https://developers.asana.com/reference/goals)                                                 | Manage organizational goals and metrics    |
 | `jobs`                        | [Jobs](https://developers.asana.com/reference/jobs)                                                   | Check status of async background jobs      |
 | `memberships`                 | [Memberships](https://developers.asana.com/reference/memberships)                                     | Manage memberships across object types     |
+| `ooo-entries`                 | [Out-of-Office Entries](https://developers.asana.com/reference/ooo-entries)                           | Manage out-of-office (OOO) entries         |
 | `organization-exports`        | [Organization Exports](https://developers.asana.com/reference/organization-exports)                   | Trigger and download org-wide exports      |
 | `portfolio-memberships`       | [Portfolio Memberships](https://developers.asana.com/reference/portfolio-memberships)                 | Read who has access to portfolios          |
 | `portfolios`                  | [Portfolios](https://developers.asana.com/reference/portfolios)                                       | Manage portfolios (project collections)    |

docs/cli-sdk-mapping.md

@@ -57,7 +57,7 @@ In the **"SDK destination"** column:
 | `--key-file PATH` | `Configuration.key_file` | Direct property (client TLS key) |
 | `--assert-hostname / --no-assert-hostname` | `Configuration.assert_hostname` | Direct property; tri-state |
 | `--user-agent VALUE` | `ApiClient.user_agent` | Client setter: assigned on the `ApiClient` after construction in `AsanaSession.__init__` |
-| `--set-default-header NAME=VALUE` | `ApiClient.set_default_header(name, value)` | Client setter: repeatable, parsed by `structured_arg.default_header_callback`; each pair applied after construction. Session-wide (rides every request) and overrides per-call `--header-params` on a key collision (SDK merges defaults on top); **not redacted in `--debug`** (see [SECURITY.md](../SECURITY.md)) |
+| `--set-default-header NAME=VALUE` | `ApiClient.set_default_header(name, value)` | Client setter: repeatable, parsed by `structured_arg.default_header_callback`; each pair applied after construction. Session-wide (rides every request) and overrides per-call `--header-params` on a key collision (SDK merges defaults on top); in `--debug` **only `Authorization` / `Proxy-Authorization` values are redacted** — any other header name is logged verbatim (see [SECURITY.md](../SECURITY.md)) |
 | `--retry-strategy VALUE` | `Configuration.retry_strategy` | Struct member: parsed by `structured_arg` (`RETRY_FIELD_SCHEMA`), applied as `retry_strategy.new(**overrides)` so unspecified fields keep the SDK defaults |
 | `--connection-pool-maxsize N` | `Configuration.connection_pool_maxsize` | Direct property |
 | `--access-token TOKEN` | `Configuration.access_token` | Direct property; default source `$ASANA_ACCESS_TOKEN` |
@@ -83,7 +83,7 @@ forwarded straight to the SDK call as a kwarg — no `runtime` round-trip.
 |---|---|---|
 | `--item-limit N` | per-call kwarg `item_limit` | Forwarded by `_make_command` |
 | `--full-payload` | per-call kwarg `full_payload=True` | Forwarded by `_make_command` |
-| `--header-params VALUE` | per-call kwarg `header_params` | Parsed by `structured_arg`; **not redacted in `--debug`** (see SECURITY.md) |
+| `--header-params VALUE` | per-call kwarg `header_params` | Parsed by `structured_arg`; in `--debug` **only `Authorization` / `Proxy-Authorization` values are redacted** — any other header name is logged verbatim (see SECURITY.md) |
 | `--request-timeout SECONDS` | per-call kwarg `_request_timeout` | Forwarded by `_make_command`; propagated to every page request by the SDK `PageIterator` |
 
 The `--limit` / `--offset` flags are docstring-derived (per-method) and appear

docs/development.md

@@ -38,13 +38,29 @@ tools/
 
 The CLI surface snapshot test (see
 [`architecture.md`](architecture.md#surface-snapshot-guardrail)) catches
-group/command/option churn introduced by an SDK bump. Procedure:
-
-1. Edit `dependencies` in `pyproject.toml` to raise the lower bound.
-2. `uv sync` to install the new SDK.
-3. `uv run pytest` — failures in `test_cli_surface.py` print the diff.
+group/command/option churn introduced by an SDK bump. The `dependencies` lower
+bound in `pyproject.toml` is kept wide (`asana>=5.0.2,<6`) — the CLI adapts to
+whatever SDK is installed — so a bump tracks the *snapshot*, not the floor.
+Procedure:
+
+1. `uv sync --upgrade-package asana` to relock and install the new SDK
+   (`uv.lock` moves; `pyproject.toml` stays).
+2. Bump `_SNAPSHOT_ASANA_VERSION` to the new version in **both**
+   `tests/test_cli_surface.py` and `tests/test_generate_python_snapshots.py` —
+   otherwise those snapshot guards silently *skip* on the new version instead
+   of checking it.
+3. `uv run pytest` — failures in `test_cli_surface.py` /
+   `test_generate_python_snapshots.py` print the diff.
 4. Review the diff; describe user-visible changes in `CHANGELOG.md`.
-5. Regenerate the fixture (exact command in `tests/test_cli_surface.py`'s module docstring).
+5. Regenerate the fixtures (exact command in each test's module docstring):
+   - `tests/fixtures/cli_surface.json` — the CLI surface. Besides commands and
+     options it pins each command's `paginatable` / `returns_iterator` /
+     `does_upload` classification, so a new array-response or upload endpoint
+     surfaces here as a fixture diff — there is no separate hand-maintained set.
+     (`tests/test_sdk_boilerplate.py` independently proves those two classifiers
+     still match the SDK source on the installed version.)
+   - `tests/fixtures/generate_python/*.py` via
+     `UPDATE_GENERATE_SNAPSHOTS=1 uv run pytest tests/test_generate_python_snapshots.py`.
 6. Verify Asana auth is still Bearer-token-only — confirm the new SDK still
    wires up only the token scheme:
 
@@ -76,7 +92,10 @@ group/command/option churn introduced by an SDK bump. Procedure:
      [developers.asana.com/llms.txt](https://developers.asana.com/llms.txt)
      (an AI-friendly Markdown index of the reference) and/or the
      individual `/reference/<group>.md` pages.
-8. Commit `pyproject.toml`, `uv.lock`, `tests/fixtures/cli_surface.json`, and `CHANGELOG.md` together.
+8. Commit `uv.lock`, the two `_SNAPSHOT_ASANA_VERSION` bumps, the regenerated
+   fixtures (`tests/fixtures/cli_surface.json` and any `generate_python/*`
+   snapshots), and `CHANGELOG.md` together (plus any group-description edits
+   from step 7).
 
 ## Trying shell completion locally
 

docs/usage.md

@@ -23,7 +23,11 @@ asana-api workspaces get-workspaces
 asana-api --access-token "2/12345..." workspaces get-workspaces
 ```
 
-No token is needed for `--help` or argument-validation errors.
+No token is needed for `--help` or command-line parsing errors (unknown
+options, a missing required argument, a malformed `NAME=VALUE`). One exception:
+a `--query` / `--exception-query` jq filter is validated against the response
+payload, so a syntactically invalid filter surfaces only *after* the API
+call — which does need a token.
 
 ## Options
 
@@ -369,7 +373,7 @@ Mirroring the SDK, `--proxy` is the only way to configure a proxy — the
 
 ### Credentials in the proxy URL are discarded
 
-As of `python-asana` 5.2.4 — the latest version checked —
+As of `python-asana` 5.2.5 — the latest version checked —
 `--proxy http://user:pass@host:port` parses, but the credentials are **never
 sent**: the SDK stack (`python-asana` → urllib3) does not turn URL userinfo
 into a `Proxy-Authorization` header. urllib3's only built-in proxy-credential
@@ -420,7 +424,7 @@ like `--project` that the Asana API accepts in place of a workspace.
 
 ## File uploads
 
-In `python-asana` 5.2.4 — the latest version checked, and most likely later
+In `python-asana` 5.2.5 — the latest version checked, and most likely later
 ones too — uploading a file whose name contains non-ASCII characters (accented
 letters, Japanese, emoji, …) stores a garbled (mojibake) filename on Asana.
 This is a long-standing bug in the SDK — see the

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "asana-api-cli"
-version = "3.2.0"
+version = "3.3.0"
 description = "Command-line wrapper around the official Asana Python SDK"
 authors = [{name = "Masanao Izumo"}]
 readme = "README.md"

src/asana_api_cli/cli.py

@@ -224,6 +224,7 @@ def _humanize_class_name(name: str) -> str:
 # a release blocker.
 _GROUP_DESCRIPTIONS: dict[str, str] = {
     "AccessRequests": "Manage private-object access requests",
+    "Agents": "Read workspace AI agents (AI Teammates)",
     "Allocations": "Manage user allocations across projects",
     "Attachments": "Upload, list, and remove file attachments",
     "AuditLogAPI": "Read domain audit log events",
@@ -238,6 +239,7 @@ def _humanize_class_name(name: str) -> str:
     "Goals": "Manage organizational goals and metrics",
     "Jobs": "Check status of async background jobs",
     "Memberships": "Manage memberships across object types",
+    "OooEntries": "Manage out-of-office (OOO) entries",
     "OrganizationExports": "Trigger and download org-wide exports",
     "PortfolioMemberships": "Read who has access to portfolios",
     "Portfolios": "Manage portfolios (project collections)",
@@ -1383,6 +1385,16 @@ def introspect_to_manifest() -> dict[str, Any]:
                     "positional": list(op.positional),
                     "has_opts": op.has_opts,
                     "paginatable": op.paginatable,
+                    # ``returns_iterator`` (array response → lazy iterator) and
+                    # ``does_upload`` (multipart file upload) pin the two runtime
+                    # classifiers that gate pagination materialization and the
+                    # ``--multibyte-filenames`` flag. Captured here so an SDK bump
+                    # that adds/removes such an endpoint surfaces in this fixture's
+                    # diff (the regen step), instead of in a hand-maintained set.
+                    # ``test_sdk_boilerplate.py`` still proves each classifier
+                    # matches the SDK source on the installed version.
+                    "returns_iterator": op.returns_iterator,
+                    "does_upload": op.does_upload,
                     "params": [
                         {
                             "name": p.name,

src/asana_api_cli/click_ext.py

@@ -45,7 +45,7 @@
 # code path is naturally dead when the flag is hidden. We instantiate
 # ``Configuration()`` because ``retry_strategy`` is an instance attribute
 # set in ``__init__`` — checking ``hasattr`` on the class itself returns
-# False even on 5.2.4.
+# False even on 5.2.5.
 _SDK_HAS_RETRY_STRATEGY: bool = hasattr(asana.Configuration(), "retry_strategy")
 
 
@@ -342,12 +342,22 @@ def _apply_global_to_runtime(name: str, value: Any) -> None:
     option declarations and the dataclass fields are authored together, and the
     inventory tests in ``test_click_ext.py`` (``TestGlobalOptionNamesInventory``)
     pin the ``GLOBAL_OPTION_NAMES`` set against ``_Runtime``'s fields — so a
-    direct ``setattr`` suffices. Every option, ``access_token`` included,
-    follows the same last-wins rule: the command-line value from the deepest
-    level reached overwrites whatever an earlier level wrote. An explicit empty
-    ``--access-token`` therefore clears a value set earlier, and
+    direct ``setattr`` suffices. Every *scalar* option, ``access_token``
+    included, follows the same last-wins rule: the command-line value from the
+    deepest level reached overwrites whatever an earlier level wrote. An
+    explicit empty ``--access-token`` therefore clears a value set earlier, and
     ``AsanaSession.from_env`` then falls back to ``$ASANA_ACCESS_TOKEN``.
 
+    ``default_headers`` is the one exception, because ``--set-default-header`` is
+    the only repeatable (accumulative) global: ``multiple=True`` already merges
+    every occurrence *at one level* into a single dict, so to honor "the later
+    occurrence wins when repeated" (``usage.md``) across levels too, values from
+    different levels are merged per-header rather than replaced wholesale. A
+    header set on the root group thus survives another ``--set-default-header``
+    given at the leaf, and a deeper level's value wins on a key collision. The
+    callback (:func:`structured_arg.default_header_callback`) yields ``None``
+    when the flag is absent, so only non-empty dicts ever reach this branch.
+
     The caller, :func:`_consume_global_options`, only ever passes names drawn
     from ``GLOBAL_OPTION_NAMES`` and only when the parameter source is
     ``ParameterSource.COMMANDLINE``. This is the single application path for
@@ -356,6 +366,9 @@ def _apply_global_to_runtime(name: str, value: Any) -> None:
     tri-state toggles' (``verify_ssl`` / ``assert_hostname`` /
     ``return_page_iterator``) ``None`` default never reaches here.
     """
+    if name == "default_headers":
+        runtime.default_headers = {**(runtime.default_headers or {}), **value}
+        return
     setattr(runtime, name, value)
 
 

src/asana_api_cli/multibyte_filename.py

@@ -16,7 +16,7 @@
 class MultibyteFilenameSupport:
     """Make multipart uploads round-trip filenames with non-ASCII characters.
 
-    In ``python-asana`` 5.2.4 (the latest version checked, and likely later
+    In ``python-asana`` 5.2.5 (the latest version checked, and likely later
     ones too), uploading a file whose name has characters outside ASCII
     stores a garbled (mojibake) name on Asana: the SDK's multipart encoder
     emits only ``filename="..."`` and omits the RFC 5987 ``filename*=``