From 86fde66050a78c6e562762642c8581836b38ec72 Mon Sep 17 00:00:00 2001 From: Ryan Lewis Date: Tue, 23 Jun 2026 00:09:23 +0100 Subject: [PATCH] docs: fix staleness in README and GitHub Pages site Audit of README.md and the docs/ site against the real CLI surface (cmd/things/main.go) surfaced drift accumulated through v0.5.0: - README: document the today-view --include-completed flag and the --on/--from/--to date filters (all undocumented); correct the "combine freely with any view" heading, which is false for the date and completed filters. - commands tab: fix the add --project/--list example (--list overrides --project), correct the project-edit flag-set claim (partial overlap, no checklist/heading flags, adds --area), fix the open example (bare titles never resolve areas), add Shell completions and Version sections. - Scope the "every command speaks JSON" claim to read commands on the homepage, commands tab, and _config.yml (write commands ignore -j). - install: document RELEASE_BASE_URL (third env var) and replace the stale v0.1.0 version pin with a vX.Y.Z placeholder (also in install.sh). --- README.md | 11 ++++++++++- docs/_config.yml | 2 +- docs/_tabs/commands.md | 37 ++++++++++++++++++++++++++++++++----- docs/_tabs/install.md | 7 +++++-- docs/index.md | 4 ++-- install.sh | 2 +- 6 files changed, 51 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 69a05b7..3c7dbda 100644 --- 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 index f3dd747..5a30d8a 100644 --- 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 index 24855b4..f42b41d 100644 --- 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 --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 --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 # 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 ` 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 index 5e6602d..ed8a3c6 100644 --- 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 index 77d68b1..6b1d9b2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,7 @@ leaves the machine. .gh-badges a.img-link { margin-right: 4px; } -**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 index b518517..0c10584 100755 --- 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