mkdir -p ~/bin
cp yandex-tracker.sh ~/bin/yandex-tracker
chmod +x ~/bin/yandex-tracker

export TOKEN='y0__...'      # OAuth токен (Tracker UI → Settings → Applications → OAuth)
export ORG_ID='1234...'     # Org ID (DevTools → Network → X-Org-Id)

TOKEN='y0__...'
ORG_ID='1234...'

sudo apt install jq   # Ubuntu/Debian
# или
brew install jq       # macOS

## Примечания

- **Автоматический тег `yandex-tracker-cli`:** При создании (`issue-create`) и обновлении (`issue-update`) задач скрипт автоматически добавляет тег `yandex-tracker-cli` (если он ещё отсутствует). Это помогает фильтровать задачи, созданные через CLI. Если нужно убрать тег — удалите его вручную через интерфейс Tracker или вызовите `issue-update` с пустым массивом `tags: []`.
- **Org-ID (Яндекс 360):** Найдите в DevTools Tracker → Network → любой запрос → заголовок `X-Org-ID`. Используется заголовок `X-Org-ID` (обратите внимание на заглавные "ID").
- **Cloud Org-ID (Yandex Cloud):** Используйте заголовок `X-Cloud-Org-ID`. В зависимости от типа организации используйте соответствующий заголовок.
- **Переходы статусов (transitions):**
  - `issue-transitions <issue-id>` — GET-запрос к V2 endpoint `/v2/issues/{id}/transitions` (возвращает список доступных переходов).
  - `issue-transition <issue-id> <transition-id>` — POST-запрос к V3 endpoint `/v3/issues/{id}/transitions/{transition}/_execute` для выполнения перехода. Требует заголовка `X-Org-ID` или `X-Cloud-Org-ID`.
- **Закрытие задач:** Команда `issue-close` устарела и может возвращать 405 в новых конфигурациях. Для закрытия используйте `issue-transition <id> close`.
- Токен можно получить в Tracker UI: Settings → Applications → OAuth → Generate new token.
- Все команды выводят JSON через `jq` для удобной дальнейшей обработки.

## Security (attachments)

Команды `attachment-download` и `attachment-upload` допускают только пути внутри разрешённой директории. Это снижает риск чтения или записи произвольных файлов при использовании CLI (в т.ч. агентом).

- **Первый запуск:** при первом вызове `attachment-download` или `attachment-upload` (если не задано `YANDEX_TRACKER_ATTACHMENTS_DIR`) скрипт в интерактивном режиме спросит: использовать папку по умолчанию `~/Downloads/YandexTrackerCLI` или ввести свой путь. Выбор сохраняется в `~/.yandex-tracker-attachments-dir` и больше не запрашивается.
- **YANDEX_TRACKER_ATTACHMENTS_DIR** — опциональная переменная окружения: базовая директория для вложений. Если задана — используется она (запрос при первом запуске не показывается). Если не задана и нет сохранённого выбора — при первом запуске запрос, иначе используется текущая директория (например, при неинтерактивном запуске).

**Когда навык используется AI-агентом:**

- Не предлагать и не выполнять `attachment-download` с путём вывода вне разрешённой директории; не использовать чувствительные пути (например `~/.ssh`, `~/.env`, `~/.yandex-tracker-env`, `/etc`, другие конфиги и секреты).
- Не предлагать и не выполнять `attachment-upload` с файлом вне разрешённой директории; не загружать файлы из чувствительных расположений (тот же список).
- Если пользователь просит скачать вложение в чувствительный путь или приложить файл из такого пути — отказать и кратко объяснить ограничение.

**Проект по неполному имени (назначить задачу в проект):**

Когда пользователь просит добавить задачу в проект, но указывает не полное имя (например «Common», «проект Common», «Менеджер»):

1. Получить список проектов: `yandex-tracker projects-list` (или `project-get` по известному id).
2. Найти совпадения по словам: отфильтровать проекты, у которых в названии (`name`), ключе (`key`) или отображаемом имени (`display`, если есть) встречаются введённые пользователем слова (желательно без учёта регистра).
3. Если найден ровно один проект — показать пользователю: «Добавить задачу в проект «<название>» (id: <id>)?» и при согласии выполнить обновление с этим проектом.
4. Если найдено несколько — перечислить их (название и id) и уточнить: «Какой из этих проектов имеется в виду?»
5. Если ничего не найдено — сообщить об этом и предложить вызвать `projects-list` и выбрать вручную.
6. Для обновления задачи использовать `issue-update`: в API v2 в теле PATCH передаётся **числовой идентификатор проекта** в поле `project`: `echo '{"project":<id>}' | yandex-tracker issue-update <issue-id>`. Использовать значение `id` из ответа списка/детали проекта (в v2 это shortId/числовой id).

## Структура

# Список очередей
yandex-tracker queues

# Создать задачу с дополнительными полями
echo '{"priority":"critical","description":"Подробности"}' | yandex-tracker issue-create BIMLAB "Новая задача"

# Добавить комментарий
yandex-tracker issue-comment BIMLAB-266 "Работаю над этим"

# Добавить spent time
yandex-tracker issue-worklog BIMLAB-266 PT2H "Исследование"

# Получить возможные переходы (список)
yandex-tracker issue-transitions BIMLAB-266 | jq .

# Выполнить переход (например, «Решить»)
yandex-tracker issue-transition BIMLAB-266 resolve

# Закрыть задачу (устарел, лучше использовать transition close)
yandex-tracker issue-transition BIMLAB-266 close

# Обновить задачу (очередь, исполнитель, проект — id проекта из projects-list)
echo '{"queue":"RAZRABOTKA"}' | yandex-tracker issue-update BIMLAB-266 # пример
echo '{"assignee":"<uid>","project":123}' | yandex-tracker issue-update BIMLAB-280

# Поиск задач через YQL
echo '{"query":"Queue = BIMLAB AND Status = Open","limit":20}' | yandex-tracker issues-search | jq .

# Список проектов
yandex-tracker projects-list | jq .

# Задачи проекта
yandex-tracker project-issues 104 | jq .

# Вложения (Attachments)
# Список вложений
yandex-tracker issue-attachments BIMLAB-266 | jq .
# Скачать файл (fileId из списка вложений) в указанный путь
yandex-tracker attachment-download BIMLAB-266 abc123 /tmp/downloaded.pdf
# Загрузить файл в задачу (с комментарием)
yandex-tracker attachment-upload BIMLAB-266 /path/to/file.pdf "Служебная записка"

# Чеклист (Checklist) — API v3 (checklistItems)
# Просмотреть чеклист задачи (id пунктов — строки, например "5fde5f0a1aee261d********")
yandex-tracker issue-checklist BIMLAB-279 | jq .
# Добавить пункт
yandex-tracker checklist-add BIMLAB-279 "Подготовить презентацию"
# Отметить пункт как выполненный (item-id из вывода issue-checklist)
yandex-tracker checklist-complete BIMLAB-279 "5fde5f0a1aee261d********"
# Удалить пункт
yandex-tracker checklist-delete BIMLAB-279 "5fde5f0a1aee261d********"

# Спринты (Agile)
yandex-tracker sprints-list | jq .
yandex-tracker sprint-issues 42 | jq .

# Справочники
yandex-tracker users-list | jq .
yandex-tracker statuses-list | jq .
yandex-tracker resolutions-list | jq .
yandex-tracker issue-types-list | jq .

# Редактирование и удаление комментариев
yandex-tracker issue-comment-edit BIMLAB-266 12345 "Обновлённый текст"
yandex-tracker issue-comment-delete BIMLAB-266 12345

# Переходы статусов
# Посмотреть список доступных переходов
yandex-tracker issue-transitions BIMLAB-266 | jq .
# Выполнить переход (например, «Решить» или «Закрыть»)
yandex-tracker issue-transition BIMLAB-266 resolve
yandex-tracker issue-transition BIMLAB-266 close

skills/yandex-tracker-cli/
├── yandex-tracker        # Исполняемый скрипт
├── SKILL.md              # Эта документация
├── ~/.yandex-tracker-env # (опционально, не в репо) Конфиг с TOKEN и ORG_ID
└── ~/.yandex-tracker-attachments-dir # (опционально) Сохранённая папка для вложений после первого запроса