tetra-cli 0.2.0__tar.gz

tetra_cli-0.2.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: tetra-cli
+Version: 0.2.0
+Summary: Standalone CLI/agent client for the Tetra API (no backend).
+Project-URL: Homepage, https://tetraoptum.com
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12.0
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# Tetra CLI
+
+[**Tetra**](https://tetraoptum.com) is an intelligent life organizer — "Tetris
+for time." It helps you align your time and money with what you actually value,
+through hierarchical **values**, **goals**, and **events**, plus the analytics
+to see where it all goes. Learn more or create a free account at
+**[tetraoptum.com](https://tetraoptum.com)**.
+
+This package is the standalone command-line client for Tetra — manage your
+values, goals, events, and time from your terminal or from any LLM agent
+(Claude Code, OpenClaw, and other tool-using assistants).
+
+It talks to the Tetra API over HTTPS using **your** API key. It has no access
+to the Tetra backend internals — it only does what your account can do.
+
+## Install
+
+```bash
+pip install tetra-cli
+```
+
+This installs the `tetra-cli` command. It depends only on public packages
+(`httpx`, `typer`, `click`).
+
+## 1. Get an API key
+
+In the Tetra web app, go to **Settings → API Keys → Create key**. Choose the
+scopes your agent needs (you can create a read-only key, or grant specific
+writes):
+
+| Scope | Lets the agent… |
+|-------|-----------------|
+| `read` | read everything in your account |
+| `events:write` | record / edit / delete events |
+| `goals:write` | create / edit / delete goals |
+| `values:write` | create / edit / delete values |
+| `tags:write` | create / edit / merge tags |
+
+The key (`tetra_…`) is shown **once**. Copy it then.
+
+> **Keep your API key secret.** It grants the same access as logging in —
+> anyone who has it can act as you, just like your password. Store it in your
+> agent's secrets/credential store, never paste it into shared chats or commit
+> it to git, and revoke it from **Settings → API Keys** if it may have leaked.
+
+## 2. Configure the CLI
+
+Save the key once (it's stored in `~/.tetra/cli_config.json`):
+
+```bash
+tetra-cli auth login tetra_your_key_here
+# defaults to https://api.tetraoptum.com; pass --url to target another server
+tetra-cli auth status      # confirm who you're authenticated as
+```
+
+Or skip the saved config and use environment variables (handy for agents /
+CI), which always take precedence:
+
+```bash
+export TETRA_API_KEY=tetra_your_key_here
+export TETRA_API_URL=http://localhost:8000        # optional; only to target a local backend (defaults to prod)
+```
+
+## 3. Install the agent skill (optional)
+
+To let an AI coding agent drive Tetra for you, install the bundled skill into
+its skills directory (defaults to Claude Code's `~/.claude/skills`):
+
+```bash
+tetra-cli skill install            # -> ~/.claude/skills/tetra-cli/SKILL.md
+tetra-cli skill install --dir /path/to/other/agent/skills   # another agent
+tetra-cli skill show               # print the skill without installing
+```
+
+## 4. Use it
+
+Goals and values are addressed by their hierarchical **name** — no UID hunting:
+
+```bash
+tetra-cli values list
+tetra-cli goals list
+tetra-cli goals get "Exercise > Weight Training"
+tetra-cli events create 2026-06-10 --goal "Exercise > Weight Training" \
+    --duration-minutes 45 --description "Bench + accessories"
+tetra-cli events list --on-date 2026-06-10
+tetra-cli dashboard week-snapshot
+```
+
+Every command supports `--help`. Output is JSON by default (ideal for agents);
+add `--pretty` for human-readable tables.
+
+## Full command surface
+
+The CLI mirrors **everything you can do in the Tetra web app** — your agent can
+act on your behalf anywhere you can act yourself. Commands are generated from
+the same operation registry the app uses, so the surface never drifts behind
+the product (a parity check in CI fails if a user-facing endpoint has no
+command). Run `tetra-cli --help` to browse the groups:
+
+| Group | What it covers |
+|-------|----------------|
+| `values`, `goals`, `events`, `tags` | the core model: create/read/update/delete, hierarchy moves, metrics, bulk edits |
+| `dashboard`, `analysis`, `data` | week/day analytics, time & spending breakdowns, full export & CSV import |
+| `scratches`, `notifications` | quick capture, one-shot reminders |
+| `gamification`, `awards`, `xp`, `capacity` | XP/level/streak, credits, gems, item shop, slot capacity |
+| `social`, `peers`, `conversations` | groups, sharing, Arena cohorts, connections, DMs & the AI thread |
+| `outcome-schemas`, `skill-trees` | reusable metric & tree templates |
+| `accounts`, `api-keys`, `onboarding` | your profile, key management, onboarding |
+| `archive`, `stripe` | restore soft-deleted items, manage your subscription |
+| `strava`, `plaid`, `issues` | activity & bank integrations, bug reports |
+
+Admin/superuser endpoints are intentionally excluded — a key only ever reaches
+your own account's data.
+
+## Using it from an LLM agent
+
+Point your agent's shell at the `tetra-cli` binary with `TETRA_API_KEY` set in
+its environment. The agent can then drive data entry, edits, and analysis on
+your account. For a Model-Context-Protocol integration (Claude Desktop, etc.),
+see the companion **tetra-mcp** package, which reads the same
+`~/.tetra/cli_config.json`.
+
+## License
+
+MIT

tetra_cli-0.2.0/README.md

@@ -0,0 +1,125 @@
+# Tetra CLI
+
+[**Tetra**](https://tetraoptum.com) is an intelligent life organizer — "Tetris
+for time." It helps you align your time and money with what you actually value,
+through hierarchical **values**, **goals**, and **events**, plus the analytics
+to see where it all goes. Learn more or create a free account at
+**[tetraoptum.com](https://tetraoptum.com)**.
+
+This package is the standalone command-line client for Tetra — manage your
+values, goals, events, and time from your terminal or from any LLM agent
+(Claude Code, OpenClaw, and other tool-using assistants).
+
+It talks to the Tetra API over HTTPS using **your** API key. It has no access
+to the Tetra backend internals — it only does what your account can do.
+
+## Install
+
+```bash
+pip install tetra-cli
+```
+
+This installs the `tetra-cli` command. It depends only on public packages
+(`httpx`, `typer`, `click`).
+
+## 1. Get an API key
+
+In the Tetra web app, go to **Settings → API Keys → Create key**. Choose the
+scopes your agent needs (you can create a read-only key, or grant specific
+writes):
+
+| Scope | Lets the agent… |
+|-------|-----------------|
+| `read` | read everything in your account |
+| `events:write` | record / edit / delete events |
+| `goals:write` | create / edit / delete goals |
+| `values:write` | create / edit / delete values |
+| `tags:write` | create / edit / merge tags |
+
+The key (`tetra_…`) is shown **once**. Copy it then.
+
+> **Keep your API key secret.** It grants the same access as logging in —
+> anyone who has it can act as you, just like your password. Store it in your
+> agent's secrets/credential store, never paste it into shared chats or commit
+> it to git, and revoke it from **Settings → API Keys** if it may have leaked.
+
+## 2. Configure the CLI
+
+Save the key once (it's stored in `~/.tetra/cli_config.json`):
+
+```bash
+tetra-cli auth login tetra_your_key_here
+# defaults to https://api.tetraoptum.com; pass --url to target another server
+tetra-cli auth status      # confirm who you're authenticated as
+```
+
+Or skip the saved config and use environment variables (handy for agents /
+CI), which always take precedence:
+
+```bash
+export TETRA_API_KEY=tetra_your_key_here
+export TETRA_API_URL=http://localhost:8000        # optional; only to target a local backend (defaults to prod)
+```
+
+## 3. Install the agent skill (optional)
+
+To let an AI coding agent drive Tetra for you, install the bundled skill into
+its skills directory (defaults to Claude Code's `~/.claude/skills`):
+
+```bash
+tetra-cli skill install            # -> ~/.claude/skills/tetra-cli/SKILL.md
+tetra-cli skill install --dir /path/to/other/agent/skills   # another agent
+tetra-cli skill show               # print the skill without installing
+```
+
+## 4. Use it
+
+Goals and values are addressed by their hierarchical **name** — no UID hunting:
+
+```bash
+tetra-cli values list
+tetra-cli goals list
+tetra-cli goals get "Exercise > Weight Training"
+tetra-cli events create 2026-06-10 --goal "Exercise > Weight Training" \
+    --duration-minutes 45 --description "Bench + accessories"
+tetra-cli events list --on-date 2026-06-10
+tetra-cli dashboard week-snapshot
+```
+
+Every command supports `--help`. Output is JSON by default (ideal for agents);
+add `--pretty` for human-readable tables.
+
+## Full command surface
+
+The CLI mirrors **everything you can do in the Tetra web app** — your agent can
+act on your behalf anywhere you can act yourself. Commands are generated from
+the same operation registry the app uses, so the surface never drifts behind
+the product (a parity check in CI fails if a user-facing endpoint has no
+command). Run `tetra-cli --help` to browse the groups:
+
+| Group | What it covers |
+|-------|----------------|
+| `values`, `goals`, `events`, `tags` | the core model: create/read/update/delete, hierarchy moves, metrics, bulk edits |
+| `dashboard`, `analysis`, `data` | week/day analytics, time & spending breakdowns, full export & CSV import |
+| `scratches`, `notifications` | quick capture, one-shot reminders |
+| `gamification`, `awards`, `xp`, `capacity` | XP/level/streak, credits, gems, item shop, slot capacity |
+| `social`, `peers`, `conversations` | groups, sharing, Arena cohorts, connections, DMs & the AI thread |
+| `outcome-schemas`, `skill-trees` | reusable metric & tree templates |
+| `accounts`, `api-keys`, `onboarding` | your profile, key management, onboarding |
+| `archive`, `stripe` | restore soft-deleted items, manage your subscription |
+| `strava`, `plaid`, `issues` | activity & bank integrations, bug reports |
+
+Admin/superuser endpoints are intentionally excluded — a key only ever reaches
+your own account's data.
+
+## Using it from an LLM agent
+
+Point your agent's shell at the `tetra-cli` binary with `TETRA_API_KEY` set in
+its environment. The agent can then drive data entry, edits, and analysis on
+your account. For a Model-Context-Protocol integration (Claude Desktop, etc.),
+see the companion **tetra-mcp** package, which reads the same
+`~/.tetra/cli_config.json`.
+
+## License
+
+MIT

tetra_cli-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tetra-cli"
+version = "0.2.0"
+description = "Standalone CLI/agent client for the Tetra API (no backend)."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "typer>=0.12.0",
+    # Imported directly (click.Choice in cli/generate.py). typer is built on
+    # click but newer typer releases no longer re-export it as a hard dep, so
+    # declare it explicitly — otherwise a clean install fails at import time.
+    "click>=8.0",
+]
+
+[project.urls]
+Homepage = "https://tetraoptum.com"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "respx>=0.21",
+]
+
+[project.scripts]
+tetra-cli = "tetra_cli.cli.app:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tetra_cli*"]
+
+# Ship the bundled agent skill (SKILL.md) in the wheel so `pip install tetra-cli`
+# delivers the client AND the instructions that teach an AI to drive it.
+[tool.setuptools.package-data]
+"tetra_cli.skill" = ["*.md"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

tetra_cli-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tetra_cli-0.2.0/tests/test_no_backend_leak.py

@@ -0,0 +1,52 @@
+"""tetra_cli must never import the backend or heavy server deps.
+
+This is the distribution invariant: the slim package is shipped to agents
+and must contain/pull in NO backend (models, routes, services, ORM). The
+guard imports every tetra_cli submodule, then asserts no forbidden module
+got loaded into sys.modules.
+"""
+from __future__ import annotations
+
+import importlib
+import pkgutil
+import sys
+
+import tetra_cli
+
+FORBIDDEN_PREFIXES = (
+    "tetra.api",
+    "tetra.core",
+    "tetra.services",
+    "tetra.db",
+    "sqlalchemy",
+    "fastapi",
+    "psycopg2",
+    "alembic",
+    "stripe",
+    "redis",
+    "llama_index",
+)
+
+
+def _all_tetra_cli_modules() -> list[str]:
+    mods = ["tetra_cli"]
+    for info in pkgutil.walk_packages(tetra_cli.__path__, prefix="tetra_cli."):
+        mods.append(info.name)
+    return mods
+
+
+def test_importing_tetra_cli_pulls_in_no_backend():
+    # Drop anything forbidden already loaded by the test session, so we measure
+    # only what tetra_cli imports trigger.
+    for name in list(sys.modules):
+        if name.startswith(FORBIDDEN_PREFIXES):
+            del sys.modules[name]
+
+    for mod in _all_tetra_cli_modules():
+        importlib.import_module(mod)
+
+    leaked = sorted(
+        name for name in sys.modules
+        if name.startswith(FORBIDDEN_PREFIXES)
+    )
+    assert leaked == [], f"tetra_cli leaked backend/heavy imports: {leaked}"

tetra_cli-0.2.0/tests/test_smoke.py

@@ -0,0 +1,6 @@
+"""Package imports and exposes its version."""
+import tetra_cli
+
+
+def test_version():
+    assert tetra_cli.__version__ == "0.1.0"

tetra_cli-0.2.0/tetra_cli/__init__.py

@@ -0,0 +1,6 @@
+"""tetra-cli: standalone, backend-free client for the Tetra API.
+
+Speaks only HTTP to a remote Tetra API with a bearer token. Contains NO
+backend server code (no models, routes, services, ORM). Safe to distribute.
+"""
+__version__ = "0.1.0"

tetra_cli-0.2.0/tetra_cli/api_client/__init__.py

@@ -0,0 +1,10 @@
+"""Shared HTTP client and operations for the Tetra API.
+
+TetraClient/TetraConfig live in .client/.config (this package — no backend).
+The operations package is the single source of truth for HTTP path, body
+shape, and parameter conversions (e.g. duration_minutes -> seconds).
+"""
+from tetra_cli.api_client.client import TetraClient, TetraClientError
+from tetra_cli.api_client.config import TetraConfig
+
+__all__ = ["TetraClient", "TetraClientError", "TetraConfig"]

tetra_cli-0.2.0/tetra_cli/api_client/client.py

@@ -0,0 +1,173 @@
+"""HTTP client wrapper for the Tetra API.
+
+Handles authentication headers, error normalization, and response parsing.
+All MCP tools use this client instead of making raw httpx calls.
+"""
+import logging
+from typing import Any
+
+import httpx
+
+from tetra_cli.api_client.config import TetraConfig
+
+logger = logging.getLogger(__name__)
+
+
+class TetraClientError(Exception):
+    """Error from the Tetra API, formatted for MCP tool output."""
+
+    def __init__(self, message: str, status_code: int = 0):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class TetraClient:
+    """Async HTTP client for the Tetra REST API."""
+
+    def __init__(self, config: TetraConfig):
+        self._config = config
+        self._client = httpx.AsyncClient(
+            base_url=config.api_url,
+            headers={
+                "Authorization": f"Bearer {config.token}",
+                # The CLI/MCP surface is agent-driven by definition. The backend
+                # honors this header in ``is_agent_request`` so created/updated
+                # entities get ``agent_touched=True`` regardless of whether the
+                # token is a real API key or a JWT minted via ``dev_token.py``.
+                "X-Tetra-Agent": "1",
+            },
+            timeout=30.0,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """GET request with error handling."""
+        response = await self._client.get(path, params=_clean_params(params))
+        return _handle_response(response)
+
+    async def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """POST request with error handling."""
+        response = await self._client.post(path, json=json)
+        return _handle_response(response)
+
+    async def put(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """PUT request with error handling."""
+        response = await self._client.put(path, json=json)
+        return _handle_response(response)
+
+    async def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """PATCH request with error handling."""
+        response = await self._client.patch(path, json=json)
+        return _handle_response(response)
+
+    async def delete(self, path: str) -> Any:
+        """DELETE request with error handling."""
+        response = await self._client.delete(path)
+        return _handle_response(response)
+
+    async def download(
+        self, path: str, params: dict[str, Any] | None = None
+    ) -> tuple[bytes, str]:
+        """GET a binary/file response. Returns ``(content_bytes, filename)``.
+
+        Used by ``output="file"`` ops whose endpoints return binary or
+        non-JSON bodies (zip, CSV, iCal). Unlike :meth:`get`, this never
+        JSON-decodes the response. On a non-2xx status it delegates to
+        :func:`_handle_response`, which raises :class:`TetraClientError`
+        (and is guarded against binary error bodies).
+
+        Args:
+            path: API path to GET.
+            params: Optional query params (None values are dropped).
+
+        Returns:
+            A tuple of the raw response bytes and a best-effort filename
+            derived from the ``Content-Disposition`` header, the last path
+            segment, or ``"download"``.
+        """
+        response = await self._client.get(path, params=_clean_params(params))
+        if not (200 <= response.status_code < 300):
+            # Reuse the non-2xx error path; it always raises TetraClientError.
+            _handle_response(response)
+        content = response.content
+        filename = (
+            _filename_from_disposition(response.headers.get("content-disposition"))
+            or path.rstrip("/").split("/")[-1]
+            or "download"
+        )
+        return content, filename
+
+
+def _filename_from_disposition(value: str | None) -> str | None:
+    """Extract the filename from a ``Content-Disposition`` header value.
+
+    Parses ``attachment; filename=foo.zip`` (and the quoted
+    ``filename="foo.zip"`` variant). Returns None when the header is absent
+    or carries no ``filename`` directive.
+
+    Args:
+        value: The raw ``Content-Disposition`` header value, or None.
+
+    Returns:
+        The unquoted filename, or None.
+    """
+    if not value:
+        return None
+    for part in value.split(";"):
+        part = part.strip()
+        if part.lower().startswith("filename="):
+            name = part[len("filename="):].strip().strip('"')
+            return name or None
+    return None
+
+
+def _clean_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Remove None values from query parameters."""
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    """Parse response and raise clear errors for non-2xx status codes."""
+    if response.status_code == 204:
+        return {"deleted": True}
+
+    if 200 <= response.status_code < 300:
+        return response.json()
+
+    # Extract error detail from response body. Guard every access: a binary
+    # error body (e.g. an upstream returning a zip on failure) must not crash
+    # the error path itself, so fall back to text, then to the status code.
+    try:
+        body = response.json()
+        detail = body.get("detail", str(body))
+    except Exception:
+        try:
+            detail = response.text or f"HTTP {response.status_code}"
+        except Exception:
+            detail = f"HTTP {response.status_code}"
+
+    status = response.status_code
+
+    if status == 401:
+        raise TetraClientError(
+            "Authentication failed. Check TETRA_API_KEY or TETRA_USERNAME.", status
+        )
+    if status == 403:
+        raise TetraClientError(f"Permission denied: {detail}", status)
+    if status == 404:
+        raise TetraClientError(f"Not found: {detail}", status)
+    if status == 400:
+        raise TetraClientError(f"Invalid request: {detail}", status)
+    if status == 422:
+        raise TetraClientError(f"Validation error: {detail}", status)
+    if status >= 500:
+        raise TetraClientError(
+            f"Server error (HTTP {status}). Is the Tetra backend running?", status
+        )
+
+    raise TetraClientError(f"Unexpected HTTP {status}: {detail}", status)