awsquery 1.1.0__tar.gz → 1.2.0__tar.gz

{awsquery-1.1.0 → awsquery-1.2.0}/.github/workflows/quality.yml

@@ -45,4 +45,8 @@ jobs:
 
       - name: Run security checks
         run: |
-          make security-check
+          make security-check
+
+      - name: Check agent reference mirror
+        run: |
+          make llms-check

{awsquery-1.1.0 → awsquery-1.2.0}/.gitignore

@@ -215,4 +215,11 @@ __marimo__/
 
 sample-responses
 test_env
-awsinfo
+awsinfo
+# Codebase graph output (local tooling)
+graphify-out/
+
+# Local working directories and captured command output
+.development/
+.worktrees/
+output.txt

awsquery-1.2.0/AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+
+Conventions for agents working **on this repository**. If you are an agent *using* awsquery to query
+AWS, you want `awsquery --docs` instead (source: `src/awsquery/agent-reference.md`).
+
+## Setup and commands
+
+```bash
+uv sync --extra dev          # create .venv with dev dependencies (or: make uv-sync)
+uv run pytest tests/ -q      # full suite, ~1700 tests, under a minute (or: make uv-test)
+make format                  # black + isort, line length 100
+make lint                    # flake8 + pylint
+make type-check              # mypy
+make ci                      # everything CI runs
+```
+
+`make install-dev` / `make test` are the pip equivalents and work the same.
+
+Run a single test with `uv run pytest tests/unit/test_x.py::TestClass::test_method -v`.
+
+## Layout
+
+- `src/awsquery/cli.py` — argument parsing, filter-group splitting, the `main()` flow
+- `src/awsquery/core.py` — API execution, multi-level parameter resolution
+- `src/awsquery/shapes.py` — botocore service-model introspection (credential-free field discovery)
+- `src/awsquery/security.py` — read-only enforcement by operation prefix
+- `src/awsquery/filters.py`, `formatters.py` — filtering and output rendering
+- `src/awsquery/default_filters.yaml`, `default_actions.yaml` — curated per-service defaults
+- `src/awsquery/agent-reference.md` — the agent/LLM reference printed by `--docs`
+
+## Non-negotiables
+
+- **The CLI is the only stable contract.** Never change the behaviour or output of an existing flag.
+  Internal APIs have no consumers: change signatures, return types and module boundaries freely, and
+  delete dead code rather than deprecating it.
+- **No pytest markers.** `@pytest.mark.parametrize` is the sole exception; every other
+  `@pytest.mark.*` is banned and the whole suite always runs. Test selection is directory-based
+  (`tests/unit/`, `tests/integration/`).
+- **Test real code.** Mock only external boundaries (boto3, filesystem, network). A test that mocks
+  the function it claims to cover, or that only asserts `mock.assert_called()`, does not count.
+- **No filler test docstrings.** No restating the test name, no TDD placeholders, no narration.
+  Comment only genuinely non-obvious cases.
+- **Check for an existing test file before creating one.** Flags belong in `test_cli_flags.py`,
+  parser behaviour in `test_cli_parser.py`, filters in `test_filter_implementation.py`.
+- **Coverage floor is 80%** (`pytest.ini`).
+
+## Documentation sync
+
+`src/awsquery/agent-reference.md` is the single source of truth for the agent-facing reference. After
+editing it, regenerate the mirror and keep the two byte-identical:
+
+```bash
+make llms      # copies it to llms-full.txt
+```
+
+A test asserts they match, and that every flag the reference documents exists in the parser. Update
+the reference in the same commit as any CLI change.
+
+## Commits
+
+Single-line summary, imperative mood, 72 characters maximum, no body. Group related changes into one
+commit; keep unrelated changes apart.

{awsquery-1.1.0 → awsquery-1.2.0}/Makefile

@@ -13,6 +13,8 @@ NC := \033[0m
 
 .PHONY: help clean install-dev test test-unit test-integration test-critical test-slow test-fast test-unit-fast \
         test-integration-fast coverage coverage-report lint format format-check type-check security-check ci build \
+        uv-sync uv-test uv-run uv-lock tool-install tool-uninstall \
+        llms llms-check \
         publish-test publish watch-tests version release update-policy validate-policy all ec2-instances s3-buckets \
         iam-users iam-roles lambda-functions cloudformation-stacks dynamodb-tables ec2-volumes \
         ec2-security-groups s3-bucket-versioning cloudwatch-alarms route53-zones shell \
@@ -36,6 +38,32 @@ help: ## Show this help message
 install-dev: ## Install development dependencies
 	pip3 install --user --break-system-packages -e ".[dev]" || pip3 install -e ".[dev]"
 
+# =============================================================================
+# UV TARGETS
+# =============================================================================
+
+uv-sync: ## Install project + dev dependencies into .venv with uv
+	uv sync --extra dev
+
+uv-test: ## Run all tests with uv
+	uv run --extra dev pytest tests/ -v
+
+uv-run: ## Run awsquery from the local checkout (use ARGS="ec2 describe-instances")
+	uv run awsquery $(ARGS)
+
+uv-lock: ## Regenerate uv.lock
+	uv lock
+
+tool-install: ## Install awsquery as a global uv tool from this checkout
+	uv tool install --force --editable .
+
+tool-uninstall: ## Remove the globally installed awsquery uv tool
+	uv tool uninstall awsquery
+
+# =============================================================================
+# TEST TARGETS
+# =============================================================================
+
 test: ## Run all tests
 	python3 -m pytest tests/ -v
 
@@ -181,6 +209,13 @@ validate-policy: ## Validate that policy.json is a valid AWS policy document
 		echo "$(GREEN)✓ policy.json validation passed$(NC)" || \
 		echo "$(RED)✗ policy.json validation failed$(NC)"
 
+llms: ## Regenerate llms-full.txt from the packaged agent reference
+	cp src/awsquery/agent-reference.md llms-full.txt
+
+llms-check: ## Verify llms-full.txt matches the packaged agent reference
+	@cmp -s src/awsquery/agent-reference.md llms-full.txt || \
+		{ echo "llms-full.txt is out of date with src/awsquery/agent-reference.md - run 'make llms'"; exit 1; }
+
 # =============================================================================
 # AWS API RESPONSE SAMPLING TARGETS (PRESERVED)
 # =============================================================================

{awsquery-1.1.0/src/awsquery.egg-info → awsquery-1.2.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: awsquery
-Version: 1.1.0
+Version: 1.2.0
 Summary: Advanced CLI tool for querying AWS APIs with flexible filtering and automatic parameter resolution
 Author-email: Florian Motlik <flo@flomotlik.me>
 License: MIT
-Project-URL: Homepage, https://github.com/yourusername/awsquery
-Project-URL: Documentation, https://awsquery.readthedocs.io
-Project-URL: Repository, https://github.com/yourusername/awsquery.git
-Project-URL: Issues, https://github.com/yourusername/awsquery/issues
-Project-URL: Changelog, https://github.com/yourusername/awsquery/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/flomotlik/awsquery
+Project-URL: Documentation, https://github.com/flomotlik/awsquery#readme
+Project-URL: Repository, https://github.com/flomotlik/awsquery.git
+Project-URL: Issues, https://github.com/flomotlik/awsquery/issues
+Project-URL: Changelog, https://github.com/flomotlik/awsquery/releases
 Keywords: aws,cli,query,cloud,devops,boto3
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -74,6 +74,25 @@ awsquery ec2 describe-instances prod web -- Tags.Name State InstanceId vpcid
 This creates endless flexibility to shape your aws cli calls, filter any output and present exactly
 the data you need during review, debugging or development.
 
+## Quick Start
+
+With [uv](https://docs.astral.sh/uv/) installed, there is nothing else to set up — no virtualenv, no
+`pip install`, not even a Python of your own:
+
+```bash
+uvx awsquery ec2 describe-instances prod web -- Tags.Name State InstanceId
+```
+
+Want it as a permanent command with tab completion?
+
+```bash
+uv tool install awsquery
+awsquery ec2 describe-instances
+```
+
+See [Installation](#installation) for aliases, version pinning, running straight from GitHub, and CI
+usage.
+
 ## Features
 
 - **Smart Multi-Level Calls**: Automatically resolves missing parameters by inferring and calling list operations
@@ -94,32 +113,229 @@ the data you need during review, debugging or development.
   == `awsquery ec2 describe-instances` (e.g. `awsquery s3 -- Name`)
 - **Parameter Passing**: Direct parameter passing to AWS APIs with `-p`/`--parameter` for advanced use cases
 - **Hint-Based Resolution**: Function selection hints with `-i`/`--input` for multi-step calls, including cross-service support and field extraction targeting
+- **Agent/LLM Mode**: `--docs` prints the complete reference in one call; `--schema`, `--list-services` and `--list-actions` answer offline with no AWS credentials
+- **Token-Efficient Output**: `--format csv|tsv|ndjson` and `--limit` keep results small enough for a context window
+- **Predictable Exit Codes**: documented codes 0-4, structured JSON errors, and no interactive prompts when stdin is not a TTY
 
 ## Installation
 
-### Via pip (Recommended)
+`awsquery` is on PyPI, so the fastest way to use it is [uv](https://docs.astral.sh/uv/): no
+virtualenv, no `pip install`, no Python version juggling. uv downloads a matching Python for you if
+you don't have one.
+
+| You want to... | Command |
+| --- | --- |
+| Try it once, install nothing | `uvx awsquery ec2 describe-instances` |
+| Use it every day (and get tab completion) | `uv tool install awsquery` |
+| Run a specific version | `uvx awsquery@1.2.0 ec2 describe-instances` |
+| Run unreleased code from GitHub | `uvx --from git+https://github.com/flomotlik/awsquery awsquery ec2` |
+| Hack on it locally | `uv run awsquery ec2` inside a checkout |
+
+### Install uv (one time)
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Homebrew
+brew install uv
+
+# Windows (PowerShell)
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+That is the only thing anyone on your team has to install. uv itself is a single binary and brings
+its own Python.
+
+### Run without installing: `uvx`
+
+```bash
+uvx awsquery ec2 describe-instances
+uvx awsquery s3 list-buckets backup -- Name CreationDate
+uvx awsquery -j cloudformation describe-stacks prod
+```
+
+The first run downloads awsquery and its dependencies into uv's cache (a few seconds). Every run
+after that starts in about a tenth of a second. Nothing is added to your `PATH`, no virtualenv is
+created, and nothing is left behind in your project.
+
+Pin an exact version when you want reproducibility, or force a check for the newest release:
+
+```bash
+uvx awsquery@1.2.0 ec2 describe-instances   # pinned, fully reproducible
+uvx awsquery@latest ec2 describe-instances  # re-checks PyPI for a newer version
+```
+
+### Make it feel like a normal command: alias
+
+Add one line to your shell config and the whole team is running the same tool without installing
+anything:
+
+```bash
+# ~/.bashrc or ~/.zshrc
+alias awsquery='uvx awsquery@latest'
+
+# pin the version instead, if you want everyone on the same release
+alias awsquery='uvx awsquery@1.2.0'
+```
+
+```fish
+# ~/.config/fish/config.fish
+alias --save awsquery 'uvx awsquery@latest'
+```
+
+```powershell
+# PowerShell $PROFILE
+function awsquery { uvx awsquery@latest @args }
+```
+
+Then use it exactly as documented everywhere else in this README:
+
+```bash
+awsquery ec2 describe-instances prod web -- Tags.Name State InstanceId
+```
+
+Two things to know about the alias route: `@latest` contacts PyPI on every invocation (so it needs
+network and adds a moment of latency), and shell tab completion does not work through an alias
+because argcomplete needs a real executable on `PATH`. If either matters to you, use
+`uv tool install` instead — it gives you the same command with neither drawback.
+
+### Install as a persistent tool: `uv tool install`
+
+```bash
+uv tool install awsquery      # installs the awsquery command into ~/.local/bin
+awsquery ec2 describe-instances
+
+uv tool upgrade awsquery      # upgrade later
+uv tool uninstall awsquery    # remove it again
+uv tool list                  # see what's installed
+```
+
+uv keeps awsquery in its own isolated environment, so it can never conflict with your project
+virtualenvs or your system Python. If the command isn't found afterwards, run `uv tool update-shell`
+(it adds uv's bin directory to your `PATH`) and restart your shell.
+
+This is the recommended setup for daily use and the one that supports
+[shell autocomplete](#enable-shell-autocomplete).
+
+### Run unreleased code straight from GitHub
+
+```bash
+# latest commit on main, run once
+uvx --from git+https://github.com/flomotlik/awsquery awsquery ec2 describe-instances
+
+# a specific branch, tag or commit
+uvx --from git+https://github.com/flomotlik/awsquery@main awsquery ec2 describe-instances
+uvx --from git+https://github.com/flomotlik/awsquery@v1.2.0 awsquery ec2 describe-instances
+
+# install that version persistently
+uv tool install git+https://github.com/flomotlik/awsquery
+```
+
+`--from` is needed because the package name (`awsquery`) has to be resolved from the repository
+while the command to execute is still `awsquery`.
+
+### Run from a local checkout
+
+```bash
+git clone https://github.com/flomotlik/awsquery.git
+cd awsquery
+
+# run the working tree directly - uv creates and syncs .venv on the fly
+uv run awsquery ec2 describe-instances
+
+# or via make
+make uv-run ARGS="ec2 describe-instances"
+
+# put your local checkout on PATH as the global awsquery command
+uv tool install --editable .   # same as: make tool-install
+```
+
+`uv run` resolves dependencies from `uv.lock`, which is committed to this repository, so every
+contributor gets an identical environment. Use `uv run --frozen awsquery ...` to fail instead of
+silently re-locking if the lockfile is out of date.
+
+### Python versions
+
+awsquery requires Python 3.10 or newer. uv fetches a suitable interpreter automatically, so you do
+not need a system Python at all. To force a specific version:
+
+```bash
+uvx --python 3.12 awsquery ec2 describe-instances
+uv tool install --python 3.12 awsquery
+uv run --python 3.12 awsquery ec2 describe-instances
+```
+
+### AWS credentials with uv
+
+uvx does not sandbox anything: the tool runs as you, with your environment and your `~/.aws`
+directory, so credentials, SSO sessions, profiles, assumed roles and `AWS_*` environment variables
+all behave exactly as they do with the AWS CLI.
+
+```bash
+AWS_PROFILE=prod uvx awsquery ec2 describe-instances
+uvx awsquery --profile prod --region eu-central-1 ec2 describe-instances
+```
+
+### Using awsquery in CI
+
+No install step is needed beyond uv itself:
+
+```yaml
+# GitHub Actions
+- uses: astral-sh/setup-uv@v6
+- run: uvx awsquery@1.2.0 -j cloudformation describe-stacks -- StackName StackStatus
+  env:
+    AWS_REGION: eu-central-1
+```
+
+Pin the version (`awsquery@1.2.0`) in CI so a new release can never change your output format
+underneath a pipeline.
+
+### Via pip
+
+If your team does not use uv, the classic routes still work:
 
 ```bash
-pip install awsquery
+pip install awsquery       # into the current environment
+pipx install awsquery      # isolated, like uv tool install
 ```
 
-### Development Installation
+### Development installation
 
 ```bash
-git clone https://github.com/yourusername/awsquery.git
+git clone https://github.com/flomotlik/awsquery.git
 cd awsquery
-pip install -e ".[dev]"
+uv sync --extra dev        # or: make uv-sync
+uv run pytest tests/ -v    # or: make uv-test
 ```
 
+The pip equivalent is `pip install -e ".[dev]"` (`make install-dev`).
+
 ### Enable Shell Autocomplete
 
 awsquery supports tab completion for AWS services and actions through argcomplete.
 
+Completion requires a real `awsquery` executable on your `PATH`, because the shell calls that
+executable to compute the candidates. So it works with `uv tool install awsquery`, `pipx install`
+and `pip install` — but **not** with a `uvx` alias, since the alias is expanded by your shell after
+completion has already run.
+
+```bash
+uv tool install awsquery   # the setup below assumes this (or pip/pipx)
+```
+
 #### Setup
 
+The `register-python-argcomplete` helper comes from argcomplete. With uv you never have to install
+it: `uvx --from argcomplete register-python-argcomplete` runs it on demand.
+
 ##### Bash
 ```bash
 # Add to ~/.bashrc or ~/.bash_profile
+eval "$(uvx --from argcomplete register-python-argcomplete awsquery)"
+
+# If argcomplete is already installed in your environment (pip/pipx users):
 eval "$(register-python-argcomplete awsquery)"
 ```
 
@@ -127,13 +343,21 @@ eval "$(register-python-argcomplete awsquery)"
 ```bash
 # Add to ~/.zshrc
 autoload -U bashcompinit && bashcompinit
-eval "$(register-python-argcomplete awsquery)"
+eval "$(uvx --from argcomplete register-python-argcomplete awsquery)"
 ```
 
 ##### Fish
 ```bash
 # Add to ~/.config/fish/config.fish
-register-python-argcomplete --shell fish awsquery | source
+uvx --from argcomplete register-python-argcomplete --shell fish awsquery | source
+```
+
+To keep shell startup instant, write the completion script to a file once and source that instead of
+calling uvx on every new shell:
+
+```bash
+uvx --from argcomplete register-python-argcomplete awsquery > ~/.awsquery-complete.sh
+echo 'source ~/.awsquery-complete.sh' >> ~/.zshrc   # or ~/.bashrc
 ```
 
 After adding the appropriate line to your shell configuration, restart your shell or source the file:
@@ -195,7 +419,8 @@ awsquery -d ec2 describe-instances
 ## Command Structure
 
 ```
-awsquery [-j|--json] [-k|--keys] [-d|--debug] [-p PARAM] [-i HINT] [--region REGION] [--profile PROFILE] SERVICE ACTION [VALUE_FILTERS...] [-- TABLE_OUTPUT_FILTERS...]
+awsquery [-j|--json] [--format FMT] [--limit N] [-k|--keys] [-d|--debug] [-p PARAM] [-i HINT] [--region REGION] [--profile PROFILE] SERVICE ACTION [VALUE_FILTERS...] [-- TABLE_OUTPUT_FILTERS...]
+awsquery --docs | --list-services | [SERVICE] --list-actions | --schema SERVICE ACTION
 ```
 
 - **SERVICE**: AWS service name (ec2, s3, iam, etc.)
@@ -209,6 +434,12 @@ awsquery [-j|--json] [-k|--keys] [-d|--debug] [-p PARAM] [-i HINT] [--region REG
 - **-i, --input HINT**: Multi-step control with cross-service support and function/field/limit hints (e.g., "ec2:desc-inst:instanceid", "desc-clus", ":arn", "::5")
 - **--region REGION**: AWS region to use for requests (e.g., us-west-2)
 - **--profile PROFILE**: AWS profile to use from ~/.aws/credentials
+- **--format FMT**: Output format - `table` (default), `json`, `csv`, `tsv`, `ndjson`
+- **--limit N**: Truncate printed rows to N (independent of the `-i ::N` resource cap)
+- **--docs**: Print the complete agent/LLM reference and exit (no AWS call)
+- **--schema**: Print an operation's input parameters and output fields (no AWS call)
+- **--list-services / --list-actions**: Enumerate services or a service's read-only actions (no AWS call)
+- **--allow-unsafe**: Permit a non-read-only operation without prompting
 
 ## Security
 
@@ -410,8 +641,148 @@ arguments). A service with no curated entry prints its available ReadOnly action
 and exits non-zero; `awsquery` with no service at all is unchanged — it still lists available
 services on stdout and exits 0.
 
+## Using awsquery with AI Agents and LLMs
+
+awsquery is built to be driven by coding agents and LLM tool calls, not just typed by hand. Three
+things make that work: the tool documents itself, it can describe any AWS operation without calling
+AWS, and its output can be made cheap in tokens.
+
+### The tool explains itself
+
+```bash
+awsquery --docs
+```
+
+Prints the complete agent reference - filter grammar, every flag, output formats, exit codes, the
+safety model, recipes and failure modes - as Markdown on stdout, in one call, with no AWS access.
+About 16 KB, sized to drop straight into a context window. This is the one command to give an agent
+that has never seen awsquery before.
+
+The same text is mirrored at [`llms-full.txt`](llms-full.txt) with an [`llms.txt`](llms.txt) index
+([llmstxt.org](https://llmstxt.org/) convention) for agents that fetch from GitHub rather than run
+the binary. [`AGENTS.md`](AGENTS.md) is the separate file for agents working *on* this repository.
+
+### Discovery without credentials
+
+These make no AWS API call, need no credentials and no region, and answer in well under a second -
+so an agent can plan a query before it has any access at all:
+
+```bash
+awsquery --list-services                      # every supported service
+awsquery ec2 --list-actions                   # that service's read-only operations
+awsquery --schema ec2 describe-instances      # inputs, and every field the API can return
+awsquery --schema -j ec2 describe-instances   # the same as JSON
+```
+
+`--schema` reads botocore's service model, so it lists all 213 output field paths for
+`ec2 describe-instances` with their types - including fields that happen to be absent from your
+account right now. It also tells you how to turn those paths into column filters.
+
+That is the difference from `-k`/`--keys`, which is still there and still useful:
+
+| | `--schema` | `-k` / `--keys` |
+| --- | --- | --- |
+| Answers | what the API **can** return | what your account **did** return |
+| AWS call | none | yes |
+| Needs credentials | no | yes |
+| Completeness | every field | only fields populated in existing resources |
+
+Use `--schema` to choose columns; use `-k` to inspect real data. `-k` follows `--format` too.
+
+### Token-efficient output
+
+Table borders and indented JSON are expensive to read. Measured on 50 rows by 5 columns: grid table
+~2340 tokens, `--format json` ~2440, `--format csv` ~790.
+
+```bash
+awsquery --format csv --limit 50 ec2 describe-instances prod -- InstanceId Tags.Name State.Name
+```
+
+- `--format table` (default), `json`, `csv`, `tsv`, `ndjson`
+- `-j`/`--json` is equivalent to `--format json`
+- `csv`, `tsv`, `ndjson` and `json` are faithful: values are not truncated, falsy values are
+  preserved, native types survive in the JSON formats (csv/tsv cells are text), and one resource
+  is always one row. `table` is a display format - it truncates long values, summarises repeats as
+  `(+N more)`, renders falsy cells blank and drops all-blank rows, so never parse it
+- An empty result set prints nothing at all under `csv`/`tsv`/`ndjson` (headers come from the
+  data); only `json` still returns `{"results": []}`. Exit status is 0 either way
+- `--limit N` truncates the printed resources in any format and notes the truncation on stderr
+- `--limit` is independent of `-i ::N`, which caps resources fed into multi-level resolution
+  (note `-i ::0` means unlimited, while `--limit 0` means zero rows)
+
+### Predictable in a tool-call loop
+
+```bash
+export AWSQUERY_NON_INTERACTIVE=1
+```
+
+A non-read-only operation is then refused immediately with exit 2 instead of prompting - awsquery
+never blocks on stdin and never returns a traceback for it. The same applies automatically whenever
+stdin is not a TTY.
+
+stdout carries data only; notices and errors go to stderr, so stdout stays parseable.
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | success, including an empty result set |
+| 1 | general or unexpected error |
+| 2 | usage error, unknown service/action, or unsafe operation refused |
+| 3 | AWS API error |
+| 4 | credentials, region or authentication failure |
+
+Unknown services and actions are caught offline, before any AWS call, so a typo costs nothing and
+comes back with the command that fixes it. Under `--format json` and `--format ndjson`, errors are
+also emitted to stderr as one compact JSON object:
+
+```json
+{"error": {"code": 2, "type": "UnknownService", "message": "Unknown service 'ec3'",
+           "hint": "Run: awsquery --list-services"}}
+```
+
+A successful run with nothing to report uses a `notice` key instead, so branching on the presence
+of `error` is safe.
+
+`AWS_REGION` is honoured as a fallback when `AWS_DEFAULT_REGION` is unset, since agents commonly set
+the former and plain boto3 ignores it.
+
+### Recommended agent workflow
+
+```bash
+awsquery --docs                                        # once, to learn the tool
+awsquery --schema -j ec2 describe-instances            # pick fields, no credentials needed
+awsquery --format csv --limit 50 \
+  ec2 describe-instances prod -- InstanceId Tags.Name State.Name   # one narrow query
+```
+
+Combined with `uvx`, an agent needs no install step at all: `uvx awsquery --docs`.
+
 ## Development
 
+### Environment setup with uv
+
+```bash
+# Create .venv and install the project plus dev dependencies from uv.lock
+uv sync --extra dev          # or: make uv-sync
+
+# Run anything inside that environment without activating it
+uv run awsquery ec2 describe-instances   # or: make uv-run ARGS="ec2 describe-instances"
+uv run pytest tests/ -v                  # or: make uv-test
+uv run black src tests
+uv run mypy src
+
+# Update the lockfile after changing dependencies in pyproject.toml
+uv lock                      # or: make uv-lock
+
+# Install your working tree as the global awsquery command
+uv tool install --editable . # or: make tool-install
+uv tool uninstall awsquery   # or: make tool-uninstall
+```
+
+`uv.lock` is committed, so `uv sync` gives every contributor byte-identical dependency versions.
+Regenerate it with `uv lock` whenever `pyproject.toml` dependencies change and commit the result.
+
+The `make` targets below use pip and the system Python; they work unchanged if you prefer that.
+
 ### Running Tests
 
 ```bash
@@ -502,9 +873,11 @@ All filters in awsquery use **case-insensitive matching** with optional anchorin
 - No operators: matches values that CONTAIN the pattern (partial match)
 
 #### Value Filters (before `--`)
-- Match against ANY field in the response data
+- Match against ANY field in the response data - both the values **and the field names**
 - ALL specified filters must match (AND logic)
 - Case-insensitive matching with optional anchoring
+- Because names are searched too, a field name used as a value filter matches every resource
+  (`awsquery ec2 describe-instances InstanceId` returns everything). Column names belong after `--`
 
 ```bash
 # "prod" matches: "production", "prod-server", "my-prod-app" (contains)
@@ -527,6 +900,9 @@ awsquery ec2 describe-instances ^prod web$
 - Match against column/field names in the output
 - Case-insensitive matching with optional anchoring
 - Multiple columns can be specified
+- Anchors apply to the full flattened key (`Instances.0.State.Name`), not the displayed header, so
+  prefer suffix anchors (`State.Name$`) for nested fields - which is why the curated defaults in
+  `default_filters.yaml` are all `$`-anchored
 
 ```bash
 # "Instance" matches: "InstanceId", "InstanceType", "InstanceName" (contains)
@@ -538,8 +914,10 @@ awsquery ec2 describe-instances -- ^Instance
 # "Name$" matches: "InstanceName", "GroupName", "Tags.Name" (ends with)
 awsquery ec2 describe-instances -- Name$
 
-# "^State.Name$" matches: only exactly "State.Name" (exact match)
-awsquery ec2 describe-instances -- ^State.Name$
+# Anchors apply to the FULL flattened key, which includes list indices
+# (e.g. "Instances.0.State.Name"), so "^State.Name$" matches nothing here.
+# Use a suffix anchor for nested fields:
+awsquery ec2 describe-instances -- State.Name$
 
 # Multiple patterns
 awsquery ec2 describe-instances -- ^Instance Name$ State
@@ -616,7 +994,7 @@ awsquery elbv2 describe-tags -i desc-clus:clusterarn prod
 # Result limiting - control how many resources are processed (default: 10)
 awsquery ssm get-parameters -i ::5  # Limit to 5 parameters
 awsquery ec2 describe-instances -i ::20  # Limit to 20 instances
-awsquery s3api list-objects -i ::0  # Unlimited (remove default limit)
+awsquery s3 list-objects-v2 -i ::0  # Unlimited (remove default limit)
 
 # Field override without function (uses inferred function)
 awsquery ecs describe-tasks -i :clusterarn  # Extract ClusterArn field
@@ -690,8 +1068,24 @@ awsquery s3 list-buckets backup -- Name Creation
 - Use more specific filters to reduce data volume
 - Consider using `--region` to target specific regions
 
+**`awsquery: command not found` after `uv tool install`**
+- Run `uv tool update-shell` and restart your shell; uv's bin directory (`~/.local/bin`) has to be on `PATH`
+- `uv tool list` shows what is installed
+
+**uvx keeps running an old version**
+- `uvx awsquery` reuses the cached version; use `uvx awsquery@latest` to re-check PyPI
+- `uv cache clean awsquery` drops the cached build entirely
+- For an installed tool use `uv tool upgrade awsquery`
+
+**Tab completion does not work**
+- Completion needs a real executable on `PATH`: use `uv tool install awsquery`, not a `uvx` alias
+- See [Enable Shell Autocomplete](#enable-shell-autocomplete)
+
 ## Requirements
 
+- Python 3.10 or newer - or just [uv](https://docs.astral.sh/uv/), which supplies its own Python
+- AWS credentials configured the same way the AWS CLI expects them
+
 The package dependencies are:
 
 - boto3>=1.35.0