quaestor-cli 0.2.0__tar.gz → 0.2.1__tar.gz

quaestor_cli-0.2.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: quaestor-cli
+Version: 0.2.1
+Summary: Command-line client for the Quaestor API — built for humans and agents.
+Project-URL: Homepage, https://quaestor.app
+Project-URL: Repository, https://github.com/neuromaxer/quaestor-lite
+Project-URL: Documentation, https://github.com/neuromaxer/quaestor-lite/blob/main/apps/cli/README.md
+Project-URL: Issues, https://github.com/neuromaxer/quaestor-lite/issues
+Keywords: agent,ai,cli,habit-tracker,quaestor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.16
+Description-Content-Type: text/markdown
+
+# quaestor-cli
+
+`qst` — a command-line client for [Quaestor](https://quaestor.app), a habit tracker.
+
+Built for two users at once: a person in a terminal, and an AI assistant acting on their
+behalf. That second audience shapes most of the design — commands are task-shaped rather
+than endpoint-shaped, streaks are addressed by name, failures are distinguishable by exit
+code, and the server's own error message is printed verbatim so an agent can relay
+something true.
+
+```bash
+uv tool install quaestor-cli
+```
+
+## Setup
+
+Create an API key in the Quaestor web app under **Profile → Developer Access**, then:
+
+```bash
+export QUAESTOR_API_KEY="qst_live_..."
+export QUAESTOR_URL="https://your-quaestor-backend"   # defaults to http://localhost:8000
+qst doctor
+```
+
+Or store it instead of exporting it — read from stdin, so it never lands in shell history:
+
+```bash
+pbpaste | qst auth login
+```
+
+The key is stored at `~/.config/quaestor/credentials.json` with mode `0600`. The
+environment variable wins if both are present.
+
+`qst` refuses to send a key over plain HTTP to anything but a loopback host. Set
+`QUAESTOR_ALLOW_INSECURE=1` only if you are knowingly running a plaintext self-hosted
+backend.
+
+## Commands
+
+```
+qst streaks                      List streaks with mode, unit and target
+qst show <streak>                Full configuration plus per-day totals, including missed days
+qst log <streak> <value>         Log a COUNT amount
+qst log <streak> --minutes 45    Log a TIME block (45, 45m, 1h30m, 1.5h)
+qst events <streak>              Individual entries, newest first, with the source of each
+qst review                       Totals, active days and current streak per streak
+qst timer start|stop|status      Control the single running timer
+qst auth login|whoami|logout     Manage the stored credential
+qst doctor                       Check URL, reachability, credential and granted scopes
+```
+
+Every command takes `--json` for machine-readable output on stdout. Every write takes
+`--dry-run`, which prints the request and sends nothing.
+
+### Windows
+
+`events`, `show` and `review` share one set of window flags: `--today`, `--week`
+(default), `--days N`, or an explicit `--from` / `--to`. The explicit and relative forms
+cannot be combined. Dates accept `today`, `yesterday`, a weekday (`mon`..`sun`, meaning
+the most recent past one), `YYYY-MM-DD`, or an offset like `-3d`.
+
+### Streaks are named, never UUIDs
+
+`<streak>` is a name. Resolution tries exact match, then unique prefix, then unique
+substring. On zero or multiple matches it exits `3`, lists the candidates, and writes
+nothing — it never guesses.
+
+```
+$ qst log r 1
+Streak 'r' is ambiguous — candidates: Reading, Running. Nothing was written.
+```
+
+### `--unit` is a safety check, not data
+
+Units belong to the streak, not the event, so `--unit` is never sent to the API. It
+asserts what you believe the streak measures and fails before writing if you are wrong —
+which is what stops an assistant logging "5 miles" as 5 km.
+
+```
+$ qst log running 5 --unit miles
+'Running' is measured in km, not miles.
+```
+
+## Exit codes
+
+An agent's only reliable error channel, so they are stable:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Bad arguments or unparseable input |
+| 2 | Authentication failed, or the key lacks the required scope |
+| 3 | Unknown or ambiguous streak |
+| 4 | Server or network error |
+
+On failure the server's `detail` message is printed verbatim to stderr.
+
+## Scopes
+
+A key only carries the permissions granted when it was created, and the server enforces
+them. Insufficient scope returns a message naming what is missing, so it is clear whether
+something is a bug or a deliberate restriction:
+
+```
+$ qst log reading 5
+API key is missing required scope(s): events:write
+```
+
+Deleting a streak has no scope at all — it is web-app only, because it also destroys every
+event, total and milestone beneath it. `qst doctor` lists the scopes a key actually holds.
+
+## Using this with an AI assistant
+
+The repository ships an [Agent
+Skill](https://github.com/neuromaxer/quaestor-lite/blob/main/skills/quaestor/SKILL.md)
+that teaches an assistant when and how to use these commands, following the
+[agentskills.io](https://agentskills.io) format. Copy it to `~/.agents/skills/` (OpenClaw)
+or `~/.hermes/skills/` (Hermes Agent).
+
+Design notes and the security model are in the [feature
+documentation](https://github.com/neuromaxer/quaestor-lite/blob/main/docs/features/agent-connect/agent-connect.md).
+
+## Requirements
+
+Python 3.12+. Depends only on `httpx` and `typer` — it speaks HTTP and never imports the
+Quaestor backend, so it installs in seconds and tolerates version skew against the server.

quaestor_cli-0.2.1/README.md

@@ -0,0 +1,126 @@
+# quaestor-cli
+
+`qst` — a command-line client for [Quaestor](https://quaestor.app), a habit tracker.
+
+Built for two users at once: a person in a terminal, and an AI assistant acting on their
+behalf. That second audience shapes most of the design — commands are task-shaped rather
+than endpoint-shaped, streaks are addressed by name, failures are distinguishable by exit
+code, and the server's own error message is printed verbatim so an agent can relay
+something true.
+
+```bash
+uv tool install quaestor-cli
+```
+
+## Setup
+
+Create an API key in the Quaestor web app under **Profile → Developer Access**, then:
+
+```bash
+export QUAESTOR_API_KEY="qst_live_..."
+export QUAESTOR_URL="https://your-quaestor-backend"   # defaults to http://localhost:8000
+qst doctor
+```
+
+Or store it instead of exporting it — read from stdin, so it never lands in shell history:
+
+```bash
+pbpaste | qst auth login
+```
+
+The key is stored at `~/.config/quaestor/credentials.json` with mode `0600`. The
+environment variable wins if both are present.
+
+`qst` refuses to send a key over plain HTTP to anything but a loopback host. Set
+`QUAESTOR_ALLOW_INSECURE=1` only if you are knowingly running a plaintext self-hosted
+backend.
+
+## Commands
+
+```
+qst streaks                      List streaks with mode, unit and target
+qst show <streak>                Full configuration plus per-day totals, including missed days
+qst log <streak> <value>         Log a COUNT amount
+qst log <streak> --minutes 45    Log a TIME block (45, 45m, 1h30m, 1.5h)
+qst events <streak>              Individual entries, newest first, with the source of each
+qst review                       Totals, active days and current streak per streak
+qst timer start|stop|status      Control the single running timer
+qst auth login|whoami|logout     Manage the stored credential
+qst doctor                       Check URL, reachability, credential and granted scopes
+```
+
+Every command takes `--json` for machine-readable output on stdout. Every write takes
+`--dry-run`, which prints the request and sends nothing.
+
+### Windows
+
+`events`, `show` and `review` share one set of window flags: `--today`, `--week`
+(default), `--days N`, or an explicit `--from` / `--to`. The explicit and relative forms
+cannot be combined. Dates accept `today`, `yesterday`, a weekday (`mon`..`sun`, meaning
+the most recent past one), `YYYY-MM-DD`, or an offset like `-3d`.
+
+### Streaks are named, never UUIDs
+
+`<streak>` is a name. Resolution tries exact match, then unique prefix, then unique
+substring. On zero or multiple matches it exits `3`, lists the candidates, and writes
+nothing — it never guesses.
+
+```
+$ qst log r 1
+Streak 'r' is ambiguous — candidates: Reading, Running. Nothing was written.
+```
+
+### `--unit` is a safety check, not data
+
+Units belong to the streak, not the event, so `--unit` is never sent to the API. It
+asserts what you believe the streak measures and fails before writing if you are wrong —
+which is what stops an assistant logging "5 miles" as 5 km.
+
+```
+$ qst log running 5 --unit miles
+'Running' is measured in km, not miles.
+```
+
+## Exit codes
+
+An agent's only reliable error channel, so they are stable:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Bad arguments or unparseable input |
+| 2 | Authentication failed, or the key lacks the required scope |
+| 3 | Unknown or ambiguous streak |
+| 4 | Server or network error |
+
+On failure the server's `detail` message is printed verbatim to stderr.
+
+## Scopes
+
+A key only carries the permissions granted when it was created, and the server enforces
+them. Insufficient scope returns a message naming what is missing, so it is clear whether
+something is a bug or a deliberate restriction:
+
+```
+$ qst log reading 5
+API key is missing required scope(s): events:write
+```
+
+Deleting a streak has no scope at all — it is web-app only, because it also destroys every
+event, total and milestone beneath it. `qst doctor` lists the scopes a key actually holds.
+
+## Using this with an AI assistant
+
+The repository ships an [Agent
+Skill](https://github.com/neuromaxer/quaestor-lite/blob/main/skills/quaestor/SKILL.md)
+that teaches an assistant when and how to use these commands, following the
+[agentskills.io](https://agentskills.io) format. Copy it to `~/.agents/skills/` (OpenClaw)
+or `~/.hermes/skills/` (Hermes Agent).
+
+Design notes and the security model are in the [feature
+documentation](https://github.com/neuromaxer/quaestor-lite/blob/main/docs/features/agent-connect/agent-connect.md).
+
+## Requirements
+
+Python 3.12+. Depends only on `httpx` and `typer` — it speaks HTTP and never imports the
+Quaestor backend, so it installs in seconds and tolerates version skew against the server.

quaestor_cli-0.2.1/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "quaestor-cli"
+version = "0.2.1"
+description = "Command-line client for the Quaestor API — built for humans and agents."
+readme = "README.md"
+requires-python = ">=3.12"
+# NOTE: no `license` yet — the repository has no LICENSE file, so publishing one here
+# would be inventing a licensing decision. Until one is chosen, PyPI shows no license,
+# which legally means all rights reserved.
+keywords = ["quaestor", "habit-tracker", "cli", "agent", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    # 0.16 is the first release that defaults pretty_exceptions_show_locals to False.
+    # Older versions render local variables — including the API key — into a crash
+    # traceback. main.py also sets the flag explicitly; this floor is belt and braces.
+    "typer>=0.16",
+]
+
+[project.urls]
+Homepage = "https://quaestor.app"
+Repository = "https://github.com/neuromaxer/quaestor-lite"
+Documentation = "https://github.com/neuromaxer/quaestor-lite/blob/main/apps/cli/README.md"
+Issues = "https://github.com/neuromaxer/quaestor-lite/issues"
+
+[project.scripts]
+qst = "quaestor_cli.main:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quaestor_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 110
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unreachable = true

{quaestor_cli-0.2.0 → quaestor_cli-0.2.1}/uv.lock

@@ -416,7 +416,7 @@ wheels = [
 
 [[package]]
 name = "quaestor-cli"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
@@ -435,7 +435,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "httpx", specifier = ">=0.27" },
-    { name = "typer", specifier = ">=0.12" },
+    { name = "typer", specifier = ">=0.16" },
 ]
 
 [package.metadata.requires-dev]

quaestor_cli-0.2.0/PKG-INFO

@@ -1,7 +0,0 @@
-Metadata-Version: 2.5
-Name: quaestor-cli
-Version: 0.2.0
-Summary: Command-line client for the Quaestor API — built for humans and agents.
-Requires-Python: >=3.12
-Requires-Dist: httpx>=0.27
-Requires-Dist: typer>=0.12

quaestor_cli-0.2.0/pyproject.toml

@@ -1,45 +0,0 @@
-[project]
-name = "quaestor-cli"
-version = "0.2.0"
-description = "Command-line client for the Quaestor API — built for humans and agents."
-requires-python = ">=3.12"
-dependencies = [
-    "httpx>=0.27",
-    "typer>=0.12",
-]
-
-[project.scripts]
-qst = "quaestor_cli.main:app"
-
-[dependency-groups]
-dev = [
-    "pytest>=8.0",
-    "pytest-asyncio>=0.23",
-    "respx>=0.21",
-    "ruff>=0.6",
-    "mypy>=1.11",
-]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/quaestor_cli"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-asyncio_mode = "auto"
-
-[tool.ruff]
-line-length = 110
-target-version = "py312"
-src = ["src", "tests"]
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B", "SIM"]
-
-[tool.mypy]
-python_version = "3.12"
-strict = true
-warn_unreachable = true