# tm-cli user guide

> For detailed usage (jobs, sprints, admin tasks, reports), run **`tm guide`** in the app.
> Korean: [README.ko.md](README.ko.md)

**TM** records your workday as an append-only **event log** and derives status, timeline, and reports from it every time.

- `tm` → opens the **dashboard (TUI)**.
- `tm <command>` → runs once (e.g. `tm status`, `tm report`).
- All times are **KST**: **09:00–18:00 is regular**, anything after is **overtime**.

---

## Contents

1. [Install & initialize](#1-install--initialize)
2. [Dashboard](#2-dashboard)
3. [Detailed usage — `tm guide`](#3-detailed-usage--tm-guide)

---

## 1. Install & initialize

**Requires** Node.js 18+.

```bash
npm i -g @seonsy44/tm-cli
```

The first time you run **`tm`**, a setup wizard runs automatically — language, name, work hours, and report settings — then opens the dashboard.

- Re-run the setup anytime: `tm setup`
- **`tm init`** — creates the config/data folders under `~/.tm` (defaults). If the current folder has `config/`+`data/`, they're imported automatically.
- Data lives in `~/.tm`. Use `tm where` to see the paths, or `TM_DIR=<path>` / `tm --dir <path>` to isolate it elsewhere.

---

## 2. Dashboard

Type `tm` and the dashboard opens.

```
╭────────────────────────────────────────────────────╮
│ TM v0.1.0                    16:31(wed) · 2026-07-08 │   >> left: name/version, right: time(day)·date
│ ────────────────────────────────────────────────── │
│ > Refactor login screen            15:27~ · 1h 4m   │   >> current activity + start·elapsed
│   JOB web-2026                                      │   >> linked Job code (for sprints)
│ ────────────────────────────────────────────────── │
│ 09:00   Spec review                          2h 4m   │  ┐
│ 11:04   API design                            20m    │  │  today's timeline
│ 11:40   Lunch                                  1h    │  │  (ongoing row prefixed with >)
│ 15:27 > Refactor login screen               1h 4m   │  ┘
│ ────────────────────────────────────────────────── │
│ 6h 31m / 8h · over 0m                               │   >> regular / available · overtime
╰────────────────────────────────────────────────────╯
  · Refactor login screen                                 >> your active sprints
  + new sprint                                            >> register a new sprint
  + start admin task                                      >> start a meeting etc.
  ──────────────
  job · report · timeoff · refresh · config · clock out   >> sub-menus / clock out
```

**Keys**

| Key | Action |
|-----|--------|
| `↑` / `↓` | move between items |
| `→` | select (not Enter) |
| `←` | back / close the dashboard |

**Markers & color**: `·` item (focus is gold), `>` running (not selectable), `+` add new. Colors are gray/white with a gold accent; no emoji.

---

## 3. Detailed usage — `tm guide`

The full usage of jobs, sprints, admin tasks, and reports lives in the in-app onboarding guide.

```bash
tm guide            # interactive guide (open a section with →, go back with ←)
tm guide --lang en  # view in English
```

The guide language follows your configured language (`tm config` → user → language).