@polza-ai/yandex-tracker-cli

v0.11.0

Published

2 days ago

CLI tool for Yandex Tracker — for humans and AI agents

0High
0Medium
0Low

polza.ai

yandex tracker cli ai agent project-management

Для людей — цветные таблицы, спиннеры, интерактивная настройка
Для AI-агентов — --json на каждой команде, готовый SKILL.md с воркфлоу
Полный цикл — 13 команд: от создания задачи до аттачей и учёта времени

Быстрый старт

npm i -g @polza-ai/yandex-tracker-cli

tracker init                    # интерактивная настройка
tracker tasks --assignee me     # мои задачи
tracker task PROJ-1             # детали задачи
tracker create -s "Исправить баг" -t bug -p critical

Команды

| Команда | Описание | Пример | |---------|----------|--------| | init | Настроить подключение | tracker init | | tasks | Поиск и список задач | tracker tasks -a me -s open | | task | Детали задачи | tracker task PROJ-123 | | create | Создать задачу | tracker create -s "Название" -t bug | | status | Изменить статус | tracker status PROJ-123 inProgress | | comment | Комментарии | tracker comment PROJ-123 "Готово" | | time | Учёт времени | tracker time PROJ-123 log 2h30m | | sprint | Текущий спринт | tracker sprint --tasks | | checklist | Чеклист задачи | tracker checklist PROJ-123 add "Тесты" | | link | Связи между задачами | tracker link PROJ-123 PROJ-456 --type blocks | | update | Обновить поля задачи | tracker update PROJ-123 -p critical | | transitions | Доступные переходы | tracker transitions PROJ-123 | | attach | Аттачи | tracker attach PROJ-123 report.pdf |

Все команды поддерживают --json для машинного вывода.

Интеграция с AI-агентами

tracker спроектирован как инструмент для AI-агентов: данные идут в stdout (JSON/таблица), логи и спиннеры — в stderr. Флаг --json возвращает стабильный конверт:

{ "ok": true,  "data": { "key": "PROJ-123", "summary": "..." } }
{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Задача не найдена" } }

Подключение

Claude Code — положите SKILL.md в корень проекта. CLAUDE.md подхватится автоматически.

Cursor / Windsurf — скопируйте SKILL.md:

cp SKILL.md .cursor/rules/tracker-workflow.md

Любой агент — используйте --json и парсите { ok, data } / { ok, error }.

Конфигурация

Глобальный конфиг

~/.tracker-cli/config.json — создаётся через tracker init:

{
  "token": "y0_AgAAAA...",
  "tokenType": "oauth",
  "orgId": "123456",
  "defaultQueue": "BACKEND",
  "apiBaseUrl": "https://api.tracker.yandex.net/v2"
}

Проектный конфиг

.tracker.json — переопределяет настройки для конкретного проекта:

{
  "queue": "BACKEND",
  "boardId": 42,
  "orgId": "654321",
  "token": "y0_AgAAAA...",
  "tokenType": "oauth",
  "statusMap": {
    "open": "open",
    "inProgress": "inProgress",
    "review": "readyForReview",
    "testing": "testing",
    "closed": "closed"
  }
}

Поля orgId, cloudOrgId, token, tokenType переопределяют значения из глобального конфига — это удобно для работы с трекерами нескольких организаций (положите свой .tracker.json в корень каждой клиентской папки). apiBaseUrl переопределить нельзя.

statusMap маппит каноничные имена статусов на реальные ключи вашего workflow.

Поиск конфига

tracker ищет ближайший .tracker.json от текущей директории вверх по дереву. Поиск останавливается на $HOME (т.е. ~/.tracker.json намеренно игнорируется); если cwd вне домашней директории — поиск идёт до корня ФС. Ближайший файл побеждает. Если проектный конфиг самодостаточен (есть token и orgId/cloudOrgId), глобальный конфиг не требуется.

⚠️ При хранении token в .tracker.json обязательно добавьте файл в .gitignore. tracker init --project предложит сделать это автоматически.

При переопределении токена userLogin всё ещё берётся из глобального конфига, поэтому --assignee me может разрешиться в неверного пользователя. При работе с другим токеном передавайте логин явно (--assignee имя).

Поддерживаются организации Яндекс 360 (OAuth) и Yandex Cloud (IAM-токен, флаг --iam при init).

init

tracker init [--iam] [--project]

| Флаг | Описание | |------|----------| | --iam | Использовать IAM-токен (Yandex Cloud) | | --project | Создать .tracker.json в текущей директории |

tasks

tracker tasks [опции]

| Флаг | Описание | |------|----------| | -q, --queue <queue> | Очередь | | -a, --assignee <login> | Исполнитель (me — текущий пользователь) | | -s, --status <status> | Статус | | --sprint <sprint> | Спринт | | --query <tql> | Произвольный TQL-запрос | | --all | Включить закрытые задачи | | -l, --limit <n> | Максимум задач (по умолчанию: 50) | | --sort <field> | Сортировка: updated, created, priority | | --json | JSON-вывод |

task

tracker task <key> [--json]

Выводит полную информацию о задаче: название, описание, статус, исполнитель, приоритет, тип, теги, связи, чеклист, комментарии, залогированное время.

create

tracker create -s "Название" [опции]

| Флаг | Описание | |------|----------| | -s, --summary <text> | Название задачи (обязательно) | | -d, --description <text> | Описание | | -F, --description-file <path> | Описание из файла (взаимоисключимо с -d) | | -q, --queue <queue> | Очередь | | -t, --type <type> | Тип: task, bug, story... (по умолчанию: task) | | -p, --priority <priority> | blocker, critical, major, normal, minor | | -a, --assignee <login> | Исполнитель | | --parent <key> | Родительская задача (для подзадач) | | --sprint <id> | Спринт | | --tag <tags...> | Теги | | --story-points <points> | Story Points (поле storyPoints) | | --field <pairs...> | Доп. поле: key=value (строка) или key:=json (число/bool/объект); повторяемо | | --dry-run | Показать тело запроса без создания | | --json | JSON-вывод |

--field — escape-hatch для любого поля API без отдельного флага:

tracker create -s "Релиз" --field deadline=2026-07-01 --field 'sp:=8' --dry-run

status

tracker status <key> <status> [-c "комментарий"] [-r <резолюция>] [--json]

Статусы: open, inProgress, review, testing, closed (маппятся через statusMap в конфиге).

-r, --resolution <key> — резолюция при закрытии (напр. fixed, successful, wontFix). Если воркфлоу требует резолюцию, а она не указана, CLI выведет список доступных. Пример: tracker status PROJ-123 closed -r successful -c "Выкачено в прод".

comment

tracker comment <key> [text] [опции]

| Флаг | Описание | |------|----------| | -f, --file <path> | Текст комментария из файла | | -l, --list | Показать все комментарии | | --json | JSON-вывод |

time

tracker time <key> <action> [duration] [опции]

Действия: start, stop, log <duration>, show

Формат длительности: 15m, 1h, 2h30m, 1d (1 день = 8 часов)

| Флаг | Описание | |------|----------| | -c, --comment <text> | Комментарий к записи | | --json | JSON-вывод |

sprint

tracker sprint [-b <id>] [--tasks | --list [--all] | --planning] [--json]

| Флаг | Описание | |------|----------| | -b, --board <id> | ID доски (или boardId из .tracker.json) | | --tasks | Показать задачи текущего спринта | | --list | Список спринтов доски (id / имя / статус / даты) | | --all | С --list: включить архивные | | --planning | Целевой спринт планирования: ближайший draft, иначе активный | | --json | JSON-вывод |

Без флагов выбора — текущий активный спринт (in_progress). --planning отдаёт спринт, куда планируют задачи (следующий), что обычно не совпадает с активным.

checklist

tracker checklist <key> [action] [text] [--json]

Действия: без аргументов — показать, add <text> — добавить, check <номер> — отметить.

link

tracker link <key> [target] [-t <type>] [--json]

Типы связей: relates (по умолчанию), blocks, depends, duplicates, parent, subtask.

Тип описывает роль key относительно target: tracker link A B -t parent делает A родителем B (прикрепить подзадачу: tracker link <родитель> <ребёнок> -t parent; родитель у задачи один, повторная привязка перезаписывает). Аналогично -t blocks — A блокирует B, -t depends — A зависит от B.

Без target — показывает существующие связи. Метка в выводе описывает роль самой запрошенной задачи: «Подзадача: Y» = она подзадача Y, «Родительская задача: Y» = она родитель Y.

update

tracker update <key> [опции]

| Флаг | Описание | |------|----------| | -s, --summary <text> | Новое название | | -d, --description <text> | Новое описание | | -F, --description-file <path> | Новое описание из файла (взаимоисключимо с -d) | | -t, --type <type> | Новый тип задачи | | -a, --assignee <login> | Новый исполнитель | | -p, --priority <priority> | Новый приоритет | | --sprint <id> | Назначить спринт | | --tag <tags...> | Теги | | --story-points <points> | Story Points (поле storyPoints) | | --field <pairs...> | Доп. поле: key=value или key:=json; повторяемо | | --dry-run | Показать тело запроса без обновления | | --json | JSON-вывод |

transitions

tracker transitions <key> [--json]

Показывает текущий статус и все доступные переходы.

attach

tracker attach <key> [file] [опции]

| Флаг | Описание | |------|----------| | -l, --list | Список аттачей | | --download <id> | Скачать аттач по ID | | -o, --output <path> | Путь для сохранения | | --json | JSON-вывод |

git clone https://github.com/polza-ai/yandex-tracker-cli.git
cd yandex-tracker-cli
npm install

npm run dev -- tasks --assignee me   # запуск через tsx
npm run build                        # компиляция в dist/
npm run typecheck                    # проверка типов
npm test                             # тесты (Vitest)

Требования

Node.js 20+
Токен Яндекс Трекера — OAuth или IAM (для Yandex Cloud)

Лицензия

MIT