tetra-cli 0.2.0

Standalone CLI/agent client for the Tetra API (no backend).

Tetra CLI

Tetra 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.

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

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):

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:

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):

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:

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