Как начать работать с SourceCraft CLI

SourceCraft CLI (src) — это интерфейс командной строки для работы на платформе SourceCraft со встроенным AI-агентом OpenCode. В opencode настроен доступ к большим языковым моделям (LLM) Code Assistant, а также установлены инструменты для работы с платформой.

С помощью SourceCraft CLI вы можете управлять репозиториями, задачами, предложениями изменений и другими ресурсами платформы прямо из терминала, не переключаясь в браузер. Также SourceCraft CLI более удобен для использования в скриптах и автоматизации, чем REST API сервиса.

Также в SourceCraft CLI реализована удобная аутентификация для git на платформе без необходимости явного использования SSH-ключей или PAT.

Помимо стандартных операций с платформой, с помощью встроенного AI-агента opencode, подключенного к Code Assistant, вы можете изучать, генерировать и отлаживать код вашего проекта. Агент интегрирован с платформой SourceCraft, имеет доступ к веткам, задачам, предложениям изменений и прочим ресурсам платформы и может выполнять многошаговые задачи прямо в контексте вашего репозитория.

Чтобы начать работать с SourceCraft CLI:

1. Подготовьтесь к работе.
2. Установите CLI.
3. Настройте CLI.
4. Протестируйте работу с ресурсами SourceCraft.
5. Протестируйте работу OpenCode.
6. Используйте AI-навыки.

Подготовьтесь к работе

1. Аутентифицируйтесь в SourceCraft.
2. Установите Git.

Установите SourceCraft CLI

SourceCraft CLI устанавливается с помощью скрипта, который:

1. Определяет вашу операционную систему и архитектуру.
2. Скачивает исполняемый файл с последней стабильной версией CLI для вашего окружения.
3. Проверяет работоспособность.
4. Добавляет CLI в переменную окружения PATH.
5. Генерирует настройки автодополнения.

Настройте SourceCraft CLI

Если вы пропустите этап первоначальной настройки, то при запуске любой команды, использующей API SourceCraft, вам все равно будет предложено пройти интерактивную настройку.

1. Чтобы запустить SourceCraft CLI, в терминале выполните команду:

   src
   

   При первом запуске будет выполнена проверка обновления, и запущена интерактивная настройка. В дальнейшем обновления будут проверяться автоматически, либо вы можете запросить их с помощью команды src update.

   Результат:

   Welcome to SourceCraft CLI!
   Let's get you set up.
   

   Примечание

   Чтобы повторно запустить процесс интерактивной настройки, используйте команду src init.

2. С помощью клавиш ↑, ↓ и Enter выберите, где сохранить аутентификационные данные:

   SourceCraft Authentication Setup
   
   Where would you like to store credentials?
   
   > Keyring (Recommended)
     Filesystem
   

   Где:

   • Keyring — системное хранилище секретов операционной системы. Это рекомендуемый и более безопасный вариант: аутентификационные данные изолированы от файловой системы, защищены на уровне ОС и недоступны другим процессам без явного разрешения. Подходит для локальных компьютеров.

   • Filesystem — файл на диске. Менее безопасный вариант, так как файл потенциально доступен любому процессу, запущенному от имени того же пользователя. Зато этот вариант работает везде, в том числе в средах без графического окружения и системного хранилища секретов, например в виртуальных машинах с минимальным набором компонентов, Docker-контейнерах, WSL и пр.

     Примечание

     В окружениях без системного хранилища секретов SourceCraft CLI выдаст предупреждение ⚠️ Keyring is not available on this system и предложит только вариант Filesystem.

3. Выберите способ аутентификации в SourceCraft:

   Which authentication method would you like to use?
   
   > IAM (Recommended)
     Personal Access Token
   

   Где:

   • IAM — короткоживущий IAM-токен Yandex Cloud. Рекомендуемый и более безопасный способ. Аутентификация будет осуществляться с использованием браузера.

   • Personal Access Token — PAT. Подходит для систем без браузера, например на виртуальных машинах или в WSL.

     Примечание

     В окружениях без браузера SourceCraft CLI выдаст предупреждение ⚠️ IAM token via OAuth is not available on this system и предложит только вариант Personal Access Token.

4. Подтвердите сохранение настроек:

   Save these settings?
   
   > Yes, save these settings
     No, cancel
   

5. (опционально) Настройте git credential helper — инструмент для удобной аутентификации git в SourceCraft без необходимости явного использования SSH-ключей или PAT:

   Configure git credential helper?
   This allows git to automatically authenticate with SourceCraft.
   
   > Yes (Recommended)
     No
   

   Совет

   Если вы пропустили настройку git credential helper, в дальнейшем вы сможете запустить ее с помощью команды src auth setup-git.

6. (опционально) Установите OpenCode:

   1. Подтвердите установку:

      Install opencode (AI coding assistant)?
      A powerful AI-powered coding assistant integrated with SourceCraft.
      
      > Yes (Recommended)
        No
      

   2. Выберите, куда установить opencode:

      • ~/.opencode/bin — стандартная директория, которая используется opencode по умолчанию при установке отдельно от SourceCraft CLI. Дает возможность работать с opencode, в том числе независимо от SourceCraft CLI. Рекомендуемый вариант.
      • ~/.config/sourcecraft/bin — изолированная директория внутри конфигурации SourceCraft CLI. В этом случае opencode можно использовать только через SourceCraft CLI. Удобно, если, например, вы хотите изолировать версию opencode, настроенную под SourceCraft, от основной.

      Where would you like to install opencode?
      
      > ~/.opencode/bin (Recommended)
        ~/.config/sourcecraft/bin (Local)
      

      Результат:

      ✓ Authentication configured successfully!
      ✓ Git credential helper configured!
      
      Installing opencode...
      ✓ Found latest version: 1.3.13
      Version 1.3.13 already installed
      ✓ Opencode installed successfully!
      
      ✓ Onboarding complete! You're ready to use SourceCraft CLI.
      

   3. Если вы выбрали способ аутентификации IAM, выполните команду:

      src auth login
      

      Результат:

      You are going to be authenticated via OAuth at Sourcecraft.
      Authentication web site will be opened.
      After your successful authentication, you will be redirected to cloud console'.
      
      Press 'enter' to continue...
      

      Нажмите Enter.

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

Утилита SourceCraft CLI настроена и готова к работе.

Протестируйте работу CLI с ресурсами SourceCraft

Посмотрите общую информацию о командах SourceCraft CLI

src --help

Получите список репозиториев в организации

src repo list <слаг_организации>

Результат:

SLUG                  DESCRIPTION                                                    VISIBILITY   LAST_UPDATED

my-first-repo         Test repository to understand platform tools.                  private      about 10 months ago 
yc-ci-cd-serverless   Пример развертывания простого веб-приложения в Yandex Cloud.   public       about 1 month ago
test-node-example     My first NodeJS application.                                   internal     about 2 days ago

Склонируйте репозиторий и перейдите в него

src clone <слаг_организации>/<слаг_репозитория>
cd <слаг_репозитория>

Создайте задачу

1. Выполните команду:

   src issue create
   

   По умолчанию все команды на создание новых сущностей запускаются в интерактивном режиме.

2. Введите название задачи:

   Create Issue
   Create a new issue in <слаг_организации>/<слаг_репозитория>
   
   Step 1 of 5
   
   Issue Title
   A descriptive title for the issue (up to 1024 characters)
   
   > <название_задачи>
   

3. Введите описание задачи. Чтобы закончить ввод, используйте сочетание клавиш Ctrl + s:

   Step 2 of 5
   
   Description
   Detailed description of the issue
   
       1 <описание_задачи>
       2 <описание_задачи>
   

4. Укажите приоритет:

   Step 3 of 5
   
   Priority
   
   ▸ Normal
       Default priority for most issues
       Trivial
       Low impact, nice to have
       Minor
       Small impact, can be addressed later
       Critical
       High impact, needs attention soon
       Blocker
       Blocking progress, must be fixed immediately
   

5. Укажите приватность задачи:

   Step 4 of 5
   
   Visibility
   
   ▸ Public
       Visible to everyone
       Private
       Only visible to repository members
   

6. Подтвердите создание задачи:

   Step 5 of 5
   
   Create Issue
   
   ▸ Yes
       No
   

   В результате будет выведена полная информация о созданной задаче.

Получите список задач

src issue list

Результат:

ID   TITLE                 STATUS   PRIORITY   ASSIGNEE     AUTHOR     ▼ CREATED AT            

2    French localization   open     normal     src-user     mr-x       about 1 hour ago    
1    Исправить баги        closed   normal     first-user   mr-x       about 3 months ago  

Чтобы получить список задач, назначенных вам, используйте параметр --assignee=@me.

Получите информацию о задаче

src issue get <идентификатор_задачи>

Результат:

ID:            2
TITLE:         French localization
LABELS:

STATUS:        open
PRIORITY:      normal
ASSIGNEE:      src-user

AUTHOR:        mr-x
UPDATED BY:    src-user
CREATED AT:    about 1 hour ago
UPDATED AT:    3 minutes ago

DESCRIPTION:   Please add French to the app.

Протестируйте работу OpenCode в SourceCraft CLI

SourceCraft CLI никак не ограничивает функциональность opencode, а расширяет ее. Вы можете продолжать использовать имеющиеся у вас плагины, правила, инструменты и пр.

При запуске через SourceCraft CLI в opencode добавляются:

• навык src-cli с описанием и руководством по CLI.
• (при нахождении в директории репозитория) информация о том, что репозиторий размещен в SourceCraft, и дополнительные инструкции по работе с ним и CLI.

1. Создайте новую ветку, в которой вы будете решать задачу, полученную на предыдущем шаге:

   git checkout -b feature/issue-2
   

2. Запустите в репозитории opencode:

   src code
   

3. Последовательно вводите запросы к AI-агенту на естественном языке, например:

   Получи список задач в репозитории.
   

   Агент воспользуется SourceCraft CLI для получения списка задач и выведет их.

   Реализуй в коде предложение пользователя из задачи с идентификатором 2 и протестируй код.
   

   Агент спланирует действия, внесет изменения в код и протестирует его.

   Сделай коммит с изменениями, отправь в удаленный репозиторий и создай предложение изменений.
   

   С помощью SourceCraft CLI агент создаст предложение изменений и выведет ссылку на него.

   Важно

   Для более гранулярного контроля за действиями агента вы можете не просить его делать коммит и отправлять изменения в репозиторий, а сделать это самостоятельно:

   git status
   git add . & git commit -m "added improvements according issue-2" & git push
   src pr create
   

4. Выйдите из opencode:

   exit
   

   Совет

   Также вы можете взаимодействовать с AI-агентом в headless-режиме без перехода в отдельный интерфейс терминала. Для этого используйте команду src do, например:

   src do "Изучи код в репозитории, расскажи как он устроен и зачем нужен."
   

5. Запросите статус проверок предложения изменений на возможность слияния с основной веткой:

   src pr checks <идентификатор_предложения_изменений>
   

   Если не указать идентификатор, команда выведет информацию о статусах проверок предложения изменений, соответствующего текущей ветке git.

   Результат:

   STATUS:               success                                
                                                              
   CODE REVIEW:          Status: success (0/0 approves)         
                                                              
   CONFLICTS:            Status: success - No conflicts         
                                                              
   CI WORKFLOWS:         security-pipeline1: success (run: 17)  
                         security-pipeline2: success (run: 17)  
                                                              
   CONFIG VALIDATIONS:   -                                      
   

Используйте AI-навыки

1. Запустите AI-навык для рецензирования вашего предложения изменений:

   src codereview
   

   Если вы находитесь в директории с репозиторием из SourceCraft, AI-агент попробует найти предложение изменений или сравнит текущую ветку с основной, проведет анализ изменений и выведет результаты в терминал.

   Совет

   Также доступны команды src prdescription для генерации описания предложения изменений и src skill для запуска пользовательских навыков.

   Попробуйте создать собственный навык по инструкции OpenCode или скачать один из готовых и запустить его с помощью команды src skill <имя_навыка> <аргументы>.

2. Выполните слияние изменений с основной веткой:

   src pr merge <идентификатор_предложения_изменений>
   

   Предложение изменений принято и добавлено в основную ветку репозитория. Чтобы перейти к ветке из другого предложения изменений, используйте команду src pr checkout.

См. также

• Справочник SourceCraft CLI
• Релизы SourceCraft CLI
• Code Assistant
• Работа с REST API SourceCraft
• Документация OpenCode
• Посмотреть квоты в SourceCraft