Document that -o writes a file for api requests #35

New Issue

2026-08-10T12:34:14Z

claude commented

2026-08-10 12:34:14 +00:00

Summary

skills/use/SKILL.md:128 советует «Pass -o json for structured output»
без оговорок, а references/tea/index.md:19 описывает -o как формат вывода.
Для tea api это не формат: -o — имя файла, куда записать тело ответа. Совет,
применённый к api, молча создаёт в рабочем каталоге файл с именем json и
оставляет stdout пустым.

Spec

skills/use/SKILL.md:128

Steps to reproduce

Выполнить запрос по совету из Tips, добавив -o json к вызову api:

tea api --login "$GITEA_LOGIN" -X POST \
    -d @tmp/pull/close-script.json \
    repos/claude-skills/tea/pulls -o json

Посмотреть, что появилось в рабочем каталоге:
```
git status --short
```

Expected

Либо структурированный вывод в stdout — как обещает совет, — либо совет,
который явно говорит: у api флаг -o означает файл, а ответ и так JSON, так
что форматировать нечего.

Actual

stdout пуст, а в корне репозитория лежит файл json на 9 КБ с телом ответа:

$ git status --short
?? json

Запрос при этом прошёл — PR создан, — но вывод «пустой», и следующая попытка
разобрать его падает на json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0). Ошибка выглядит как отказ сервера, хотя дело в флаге.

Справка CLI однозначна (tea api --login "$GITEA_LOGIN" --help):

--output string, -o string   Write response body to file instead of stdout
                             (use '-' for stdout)

references/tea/helpers.md:29 описывает это верно. Расходятся два других
места:

файл	что сказано	верно для
`references/tea/helpers.md:29`	`--output/-o <file>` — записать тело в файл	`api`
`references/tea/index.md:19`	`--output, -o <fmt>` — формат вывода	entity-команд
`skills/use/SKILL.md:128`	«Pass `-o json` for structured output»	entity-команд, без оговорки

Совет в Tips идёт последним и без контекста, а раздел «Rich payloads» прямо над
ним учит звать именно api — так две соседние инструкции и складываются в
ошибку.

Environment

macOS 25.5.0, tea 0.14.1
claude-skills/tea, ветка feat/close-script

Acceptance criteria

в skills/use/SKILL.md совет про -o json ограничен entity-командами и
называет поведение -o у api
references/tea/index.md помечает -o как флаг entity-команд, а не
глобальный
references/tea/helpers.md и index.md больше не противоречат друг
другу по -o

## Summary `skills/use/SKILL.md:128` советует «Pass `-o json` for structured output» без оговорок, а `references/tea/index.md:19` описывает `-o` как формат вывода. Для `tea api` это не формат: `-o` — имя файла, куда записать тело ответа. Совет, применённый к `api`, молча создаёт в рабочем каталоге файл с именем `json` и оставляет stdout пустым. ## Spec skills/use/SKILL.md:128 ## Steps to reproduce 1. Выполнить запрос по совету из Tips, добавив `-o json` к вызову `api`: ```bash tea api --login "$GITEA_LOGIN" -X POST \ -d @tmp/pull/close-script.json \ repos/claude-skills/tea/pulls -o json ``` 2. Посмотреть, что появилось в рабочем каталоге: ```bash git status --short ``` ## Expected Либо структурированный вывод в stdout — как обещает совет, — либо совет, который явно говорит: у `api` флаг `-o` означает файл, а ответ и так JSON, так что форматировать нечего. ## Actual stdout пуст, а в корне репозитория лежит файл `json` на 9 КБ с телом ответа: ``` $ git status --short ?? json ``` Запрос при этом прошёл — PR создан, — но вывод «пустой», и следующая попытка разобрать его падает на `json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)`. Ошибка выглядит как отказ сервера, хотя дело в флаге. Справка CLI однозначна (`tea api --login "$GITEA_LOGIN" --help`): ``` --output string, -o string Write response body to file instead of stdout (use '-' for stdout) ``` `references/tea/helpers.md:29` описывает это верно. Расходятся два других места: | файл | что сказано | верно для | |---|---|---| | `references/tea/helpers.md:29` | `--output/-o <file>` — записать тело в файл | `api` | | `references/tea/index.md:19` | `--output, -o <fmt>` — формат вывода | entity-команд | | `skills/use/SKILL.md:128` | «Pass `-o json` for structured output» | entity-команд, без оговорки | Совет в Tips идёт последним и без контекста, а раздел «Rich payloads» прямо над ним учит звать именно `api` — так две соседние инструкции и складываются в ошибку. ## Environment - macOS 25.5.0, `tea` 0.14.1 - claude-skills/tea, ветка `feat/close-script` ## Acceptance criteria - [ ] в `skills/use/SKILL.md` совет про `-o json` ограничен entity-командами и называет поведение `-o` у `api` - [ ] `references/tea/index.md` помечает `-o` как флаг entity-команд, а не глобальный - [ ] `references/tea/helpers.md` и `index.md` больше не противоречат друг другу по `-o`

claude added this to the Self-improvement milestone 2026-08-10 12:34:14 +00:00

claude added the

comp/use labels 2026-08-10 12:34:14 +00:00

naudachu referenced this issue from a commit

2026-08-10 15:05:41 +00:00

docs: separate the API-only flags from the ones needing a checkout

naudachu closed this issue

2026-08-10 15:08:27 +00:00