otta-cli

使用 `otta-cli` 从终端自动化 `otta.fi` 工作流程。该工具通常用于跟踪工作时间、缺勤和病假：身份验证、检查配置/缓存、检查帐户状态、管理工作时间（列表/添加/更新/删除）、浏览缺勤、获取假期以及生成组合/详细日历报告。当请求需要 CLI 优先的 Otta 操作、“OTTA_CLI_*”环境设置、机器可读的“--format json”输出或诊断 auth/config/API 验证错误时，触发此技能。

## 概述（中文）

使用 `otta-cli` 从终端自动化 `otta.fi` 工作流程。该工具通常用于跟踪工作时间、缺勤和病假：身份验证、检查配置/缓存、检查帐户状态、管理工作时间（列表/添加/更新/删除）、浏览缺勤、获取假期以及生成组合/详细日历报告。当请求需要 CLI 优先的 Otta 操作、“OTTA_CLI_*”环境设置、机器可读的“--format json”输出或诊断 auth/config/API 验证错误时，触发此技能。

## 原文

# Otta CLI

Use this skill to execute Otta time-tracking tasks end-to-end with repeatable CLI commands.

Main repository: https://github.com/mekedron/otta-cli

## Quick Start

1. Use the `otta` binary directly.

2. Verify command surface and storage paths.

```bash
otta --help
otta config path
otta config cache-path
```

3. Authenticate and hydrate cache.

```bash
otta auth login --username "$OTTA_CLI_USERNAME" --password "$OTTA_CLI_PASSWORD" --format json
otta status --format json
```

- `status` updates cached user metadata (for `user` and `worktimegroup` fallbacks used by worktimes/holidays/calendar commands).
- For non-interactive automation, prefer `--password-stdin` or secret env handling to reduce shell history exposure.

## Command Recipes

Use explicit dates/times in `YYYY-MM-DD` and `HH:MM` formats.

List worktimes:

```bash
otta worktimes list --date 2026-02-20 --format json
```

Add worktime:

```bash
otta worktimes add \
  --date 2026-02-20 \
  --start 09:00 \
  --end 17:00 \
  --pause 30 \
  --project <project-id> \
  --worktype <worktype-id> \
  --description "Example task description" \
  --format json
```

- `--user` is optional if `OTTA_CLI_USER_ID` or cached user ID exists.

Update worktime:

```bash
otta worktimes update --id <worktime-id> --start 10:00 --end 18:00 --format json
```

- Send at least one changed field with `--id`.

Delete worktime:

```bash
otta worktimes delete --id <worktime-id> --format json
```

Fetch holidays/workday calendar:

```bash
otta holidays \
  --from 2026-02-20 \
  --to 2026-02-29 \
  --worktimegroup <worktimegroup-id> \
  --format json
```

- `--worktimegroup` is optional if `OTTA_CLI_WORKTIMEGROUP_ID` or cached value exists.

Browse absences:

```bash
otta absence browse \
  --from 2026-02-01 \
  --to 2026-02-28 \
  --format json
```

Fetch current cumulative saldo:

```bash
otta saldo --format json
```

Generate combined calendar overview:

```bash
otta calendar overview \
  --from 2026-02-01 \
  --to 2026-02-28 \
  --format json
```

Generate detailed calendar day-by-day report:

```bash
otta calendar detailed \
  --from 2026-02-01 \
  --to 2026-02-28 \
  --format json
```

Use alternate duration units when totals are minute-based:

```bash
otta calendar detailed --from 2026-02-01 --to 2026-02-28 --format json --duration-format hours
otta worktimes browse --from 2026-02-01 --to 2026-02-28 --format json --duration-format days
```

- `--duration-format` values: `minutes` (default), `hours`, `days`, `hhmm`
- day conversion is fixed at `1 day = 24h = 1440 minutes`

Generate absence comment text:

```bash
otta absence comment \
  --type sick \
  --from 2026-02-20 \
  --to 2026-02-20 \
  --details "Flu symptoms" \
  --format json
```

## Environment Variables

Use these variables when running in CI/non-interactive environments:

- `OTTA_CLI_CONFIG_PATH`
- `OTTA_CLI_CACHE_PATH`
- `OTTA_CLI_API_BASE_URL`
- `OTTA_CLI_CLIENT_ID`
- `OTTA_CLI_USERNAME`
- `OTTA_CLI_PASSWORD`
- `OTTA_CLI_ACCESS_TOKEN`
- `OTTA_CLI_TOKEN_TYPE`
- `OTTA_CLI_REFRESH_TOKEN`
- `OTTA_CLI_TOKEN_SCOPE`
- `OTTA_CLI_USER_ID`
- `OTTA_CLI_WORKTIMEGROUP_ID`

## Agent Operating Rules

1. Prefer `--format json` for all data-producing commands and parse response fields instead of scraping text output.
2. `worktimes list/browse/report` are worktime-only and never include absences; do not infer absences from empty worktime rows.
3. For user schedule checks/log interpretation, prefer `calendar detailed --format json` first; use `calendar overview` as lighter fallback.
4. Use `--duration-format` when users request non-minute output; keep raw minute values for auditability.
5. Run `status --format json` before operations that rely on cached user/worktimegroup metadata.
6. Validate dates/times before command execution (`YYYY-MM-DD`, `HH:MM`).
7. Run `worktimes list` before `update` or `delete` when IDs are not explicitly known.
8. Return exact command, exit code, and concise stderr message when failures happen.
9. Never print raw credentials or tokens in summaries.

## Failure Recovery

- `no access token configured (run \`otta auth login\`)`
  - Run `auth login`, then rerun `status`.
- `username is required (use --username)`
  - Pass `--username` or set `OTTA_CLI_USERNAME`.
- `--worktimegroup is required (...)`
  - Pass `--worktimegroup`, set `OTTA_CLI_WORKTIMEGROUP_ID`, or run `status` to refresh cache.
- `--date must be YYYY-MM-DD`, `--start must be HH:MM`, `--to must be greater than or equal to --from`
  - Correct input format/order, rerun command.
- `directory ... is contained in a module that is not one of the workspace modules listed in go.work`
  - Build/run with `GOWORK=off` in this repository context.