# Set up the Time Momentum command line tm

Guide for AI agents (Claude Code, Cursor, Codex). With tm you operate Time Momentum on the human's behalf: time entries, clients, projects, orders, invoices, payments and reports.

## Rule: the API key stays out of the conversation

- Never ask the human for the API key. Never read it from anywhere (clipboard, config files, environment variables) and never print it.
- Do not run `tm auth login` yourself. It asks for the key with hidden input, which only works in a real terminal. The human runs it in a terminal of their own.

## 1. Check Node.js

`node -v` must show at least 22.14. If Node.js is missing or older, ask the human before installing or upgrading it (macOS: `brew install node`, otherwise https://nodejs.org).

## 2. Install tm

- macOS and Linux: `curl -fsSL https://app.time-momentum.com/install-cli.sh | sh`
- Windows (PowerShell): `irm https://app.time-momentum.com/install-cli.ps1 | iex`

If tm is already installed (`tm version`), `tm update` is enough. The installer adds tm's directory to the PATH; your running shell does not see that yet. In your session, call tm by its full path: `~/.time-momentum/bin/tm` (Windows: `%USERPROFILE%\.time-momentum\bin\tm.cmd`).

## 3. Let the human sign in

Ask the human to open a new terminal window (outside your session) and run:

```
tm auth login
```

The command asks for the API key with hidden input. The human creates the key in Time Momentum under Datenquellen › CLI: read access covers projects and time entries, write access everything else. If the new terminal cannot find tm, give the human the full path. Wait until they are done.

## 4. Verify

`tm whoami --json` shows the workspace and the permission (`read` or `write`).

## 5. Set up the guide for future tasks

- Claude Code: `tm skill --install` sets up the "time-momentum" skill.
- Other agents: read `tm skill` and keep the essentials in your persistent instructions.

## 6. Report back

Tell the human briefly whether everything worked.

## Troubleshooting

- `command not found: tm`: use the full path or a new terminal.
- Exit code 3 (`unauthorized`): the key is invalid or revoked. The human creates a new one.
- All commands: `tm --json`, details per group: `tm schema <group> --json`.