ryanlewis · ryanlewis · Jun 22, 2026 · Jun 22, 2026
diff --git a/README.md b/README.md
@@ -79,13 +79,22 @@ project literally called `Inbox` would need `things -p Inbox`.
 | `trash` | Trashed tasks |
 | `deadlines` | Tasks with a deadline |
 
-Filters (combine freely with any view):
+Filters:
 
 | Flag | Description |
 | --- | --- |
 | `-p, --project NAME` | Filter by project name or UUID |
 | `-a, --area NAME` | Filter by area name or UUID |
 | `-t, --tag NAME` | Filter by tag name |
+| `--on DATE` | Only tasks scheduled on `YYYY-MM-DD` (or RFC3339); on `deadlines`, filters by deadline |
+| `--from DATE` | Only tasks scheduled on or after the date |
+| `--to DATE` | Only tasks scheduled on or before the date |
+| `--include-completed` | On `today` only: also show completed/cancelled items Things hasn't logged out of Today yet |
+
+`-p`/`-a`/`-t` combine with any view. The date filters (`--on`, `--from`,
+`--to`) apply to date-filterable views — `today`, `upcoming`, `anytime`,
+`someday`, `deadlines`, and project listings — and `--on` can't be combined
+with `--from`/`--to`. `--include-completed` applies to the `today` view only.
 
 Examples:
 

diff --git a/docs/_config.yml b/docs/_config.yml
@@ -7,7 +7,7 @@ title: things-cli
 tagline: A small, AI-friendly CLI for Things3 on macOS
 description: >-
   Read tasks, projects, areas, and tags straight from Things3.
-  Every command speaks JSON. A bundled agent skill teaches Claude
+  Every read command speaks JSON. A bundled agent skill teaches Claude
   Code, Codex, and Pi when to reach for `things` instead of guessing.
 
 url: "https://things.rlew.io"

diff --git a/docs/_tabs/commands.md b/docs/_tabs/commands.md
@@ -4,8 +4,9 @@ icon: fas fa-list
 order: 2
 ---
 
-Every subcommand accepts `-j` / `--json` for structured output. Run
-`things --help` or `things <subcommand> --help` for the full flag list.
+Read commands (`list`/views, `projects`, `areas`, `tags`, `show`, `search`)
+accept `-j` / `--json` for structured output. Run `things --help` or
+`things <subcommand> --help` for the full flag list.
 
 ## Listing
 
@@ -54,7 +55,8 @@ things search "release" --json
 things add "Buy milk"
 things add "Ship the thing" --when today --tags work,urgent
 things add "Pay invoice" --deadline 2026-06-01 --notes "Send PDF"
-things add "Review PR" --project "things-cli" --list "Open source"
+things add "Review PR" --project "things-cli"
+things add "Plan offsite" --list "Open source"   # --list takes a project or area; it overrides --project if both are given
 things add "Groceries" --checklist "Milk\nBread\nEggs"
 ```
 
@@ -79,7 +81,11 @@ things edit 3 --append-checklist "Almond too"
 things edit 3 --complete                 # also: --cancel, --duplicate, --reveal
 ```
 
-`things project edit` mirrors the same flag set for projects.
+`things project edit` takes most of the same flags (`--title`, `--notes`,
+`--prepend-notes`/`--append-notes`, `--when`, `--deadline`, `--tags`,
+`--add-tags`, `--complete`, `--cancel`, `--duplicate`, `--reveal`) plus
+`--area`/`--area-id` to move the project. It has no checklist or
+heading flags.
 
 ## Completing and cancelling
 
@@ -108,7 +114,9 @@ things import < payload.json  # batch create/update via the Things JSON URL sche
 things open today              # built-in views
 things open inbox
 things open <uuid>             # specific task or project
-things open "Side projects"    # area or project by name
+things open "Weekly Review"    # task or project by title
+things open --area "Side projects"   # an area (bare titles never resolve areas)
+things open --tag urgent             # a tag
 ```
 
 ## Agent skill
@@ -128,6 +136,25 @@ things skill uninstall claude  # remove the installed copy
 The skill is bundled into the binary, so a plain `things` upgrade
 refreshes every installed copy on next `install`.
 
+## Shell completions
+
+`things completions <shell>` prints a completion script for `bash`, `zsh`,
+or `fish`:
+
+```sh
+things completions zsh > ~/.things-completions.zsh   # then source it from ~/.zshrc
+```
+
+Homebrew-cask installs wire these up automatically.
+
+## Version
+
+```sh
+things version       # or: things --version / things -v
+```
+
+Prints the version, commit, and build date.
+
 ## Caching
 
 `things` caches the last list it printed in

diff --git a/docs/_tabs/install.md b/docs/_tabs/install.md
@@ -41,14 +41,17 @@ Downloads the latest release for your architecture, verifies the
 checksum against `checksums.txt`, and installs the `things` binary to
 `/usr/local/bin`.
 
-The script reads two optional environment variables:
+The script reads three optional environment variables:
 
 ```sh
 # Install somewhere other than /usr/local/bin
 INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/{{ site.repository }}/main/install.sh | sh
 
 # Pin a specific version (defaults to the latest release)
-VERSION=v0.1.0 curl -fsSL https://raw.githubusercontent.com/{{ site.repository }}/main/install.sh | sh
+VERSION=vX.Y.Z curl -fsSL https://raw.githubusercontent.com/{{ site.repository }}/main/install.sh | sh
+
+# Override the asset download base URL (for mirrors / testing)
+RELEASE_BASE_URL=https://example.com/things curl -fsSL https://raw.githubusercontent.com/{{ site.repository }}/main/install.sh | sh
 ```
 
 ## go install

diff --git a/docs/index.md b/docs/index.md
@@ -20,7 +20,7 @@ leaves the machine.
 .gh-badges a.img-link { margin-right: 4px; }
 </style>
 
-**AI-friendly by design.** Every command speaks JSON (`-j` / `--json`)
+**AI-friendly by design.** Every read command speaks JSON (`-j` / `--json`)
 for clean piping into `jq`, agents, or scripts. A bundled agent skill
 ships in the binary itself — `things skill install claude` drops it into
 Claude Code, and `things skill show` prints the neutral source so you
@@ -48,7 +48,7 @@ things complete 3
 things open today
 ```
 
-Every command takes `-j` / `--json` for structured output:
+Every read command takes `-j` / `--json` for structured output:
 
 ```sh
 things upcoming --json | jq '.[] | select(.deadline)'

diff --git a/install.sh b/install.sh
@@ -6,7 +6,7 @@
 #
 # Environment:
 #   INSTALL_DIR        target directory for the binary (default: /usr/local/bin)
-#   VERSION            version tag to install, e.g. v0.1.0 (default: latest release)
+#   VERSION            version tag to install, e.g. vX.Y.Z (default: latest release)
 #   RELEASE_BASE_URL   override the asset download base URL (for mirrors / testing)
 
 set -eu