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
