Getting started with the SourceCraft CLI

SourceCraft CLI (src) is your command line interface for the SourceCraft platform with a built-in OpenCode AI agent. opencode is preconfigured for access to Code Assistant's large language models (LLMs) and features the tools you need to use the platform.

With the SourceCraft CLI, you can manage repositories, issues, pull requests, and the platform's other resources directly from your terminal without switching to a browser. It is also better suited for scripting and automation than the bundled REST API.

The SourceCraft CLI also offers convenient git authentication on the platform without the explicit use of SSH keys or PATs.

On top of the standard platform operations, the built-in opencode AI agent, hooked up to Code Assistant, allows you to explore, generate, and debug your project code. The agent is deeply integrated with SourceCraft and has access to branches, issues, pull requests, and the platform's other resources for multi-turn issues directly within the context of your repository.

To get started with the SourceCraft CLI:

1. Get ready.
2. Install the CLI.
3. Configure the CLI.
4. Test CLI interaction with SourceCraft resources.
5. Test OpenCode.
6. Use the AI skills.

Get ready

1. Get authenticated in SourceCraft.
2. Install Git.

Install the SourceCraft CLI

The SourceCraft CLI is installed via a script that:

1. Identifies your OS and architecture.
2. Downloads the executable with the latest stable CLI version for your environment.
3. Performs a health check.
4. Adds the CLI to the PATH environment variable.
5. Generates autocompletion settings.

Configure the SourceCraft CLI

If you skip the initial setup, any command that uses the SourceCraft API will prompt you to complete interactive setup.

1. To start the SourceCraft CLI, run the following command in the terminal:

   src
   

   On first start , an update check will be performed followed by interactive setup. From then onward, update checks will be performed automatically, or you can request them using the src update command.

   Result:

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

   Note

   To re-start interactive setup, use the src init command.

2. Use the ↑, ↓, and Enter keys to choose where to store authentication credentials:

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

   Where:

   • Keyring: System secret storage of the operating system. This is the recommended and more secure option: credentials are isolated from the filesystem, protected at the OS level, and inaccessible to other processes without explicit permission. Suitable for local machines.

   • Filesystem: A file on disk. Less secure, as the file may be accessible to any process run by the same user. On the upside, this option works everywhere, including environments with no UI or system secret storage, such as minimal VMs, Docker containers, and WSL.

     Note

     In environments without a system secret storage, the SourceCraft CLI will display the ⚠️ Keyring is not available on this system warning and offer the Filesystem option only.

3. Select the authentication method in SourceCraft:

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

   Where:

   • IAM: Short-lived Yandex Cloud IAM token. The recommended and more secure method that uses browser-based authentication.

   • Personal Access Token: PAT. Suitable for browserless systems (e.g., VMs or WSL).

     Note

     In browserless environments, the SourceCraft CLI will display the ⚠️ IAM token via OAuth is not available on this system warning and offer the Personal Access Token option only.

4. Confirm saving the settings:

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

5. Optionally, set up the git credential helper, a tool for convenient git authentication in SourceCraft without explicit use of SSH keys or PATs:

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

   Tip

   If you skip the git credential helper setup, you can start it later using the src auth setup-git command.

6. Optionally, confirm installation of OpenCode:

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

   OpenCode will be installed into an isolated directory ~/.config/sourcecraft/bin within the SourceCraft CLI configuration. This will allow you to use it via src for integration with Code Assistant and the SourceCraft platform. The configuration of the separately installed OpenCode will remain unchanged and available independently of SourceCraft.

   Result:

   ✓ 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.
   

7. If you have selected IAM authentication, run this command:

   src auth login
   

   Result:

   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...
   

   Press Enter.

   A browser window will open for authentication. You may close it and continue using the terminal.

The SourceCraft CLI is now configured and ready for use.

Test CLI interaction with SourceCraft resources

View general info about SourceCraft CLI commands

src --help

Get a list of repositories in the organization

src repo list <organization_slug>

Result:

SLUG                  DESCRIPTION                                                    VISIBILITY   LAST_UPDATED

my-first-repo         Test repository to understand platform tools.                  private      about 10 months ago 
yc-ci-cd-serverless   Example of deploying a simple web app in Yandex Cloud.   public       about 1 month ago
test-node-example     My first NodeJS application.                                   internal     about 2 days ago

Clone the repository and navigate to it

src clone <organization_slug>/<repository_slug>
cd <repository_slug>

Create an issue

1. Run this command:

   src issue create
   

   By default, all commands that create new entities run in interactive mode.

2. Enter a name for the issue:

   Create Issue
   Create a new issue in <organization_slug>/<repository_slug>
   
   Step 1 of 5
   
   Issue Title
   A descriptive title for the issue (up to 1024 characters)
   
   > <issue_name>
   

3. Enter a description for the issue. To finish input, use the keyboard shortcut Ctrl + s:

   Step 2 of 5
   
   Description
   Detailed description of the issue
   
       1 <issue_description>
       2 <issue_description>
   

4. Specify priority:

   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. Specify issue privacy:

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

6. Confirm creating the issue:

   Step 5 of 5
   
   Create Issue
   
   ▸ Yes
       No
   

   This will display the full details of the new issue.

Getting a list of issues

src issue list

Result:

ID   TITLE                 STATUS   PRIORITY   ASSIGNEE     AUTHOR     ▼ CREATED AT            

2    French localization   open     normal     src-user     mr-x       about 1 hour ago    
1    Fix bugs        closed   normal     first-user   mr-x       about 3 months ago  

To get a list of issues assigned to you, use the --assignee=@me parameter.

Getting issue information

src issue get <issue_ID>

Result:

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.

Test OpenCode in the SourceCraft CLI

The SourceCraft CLI does not limit the opencode functionality in any way but expands it. You can continue using your existing plugins, rules, tools, etc.

When launched via the SourceCraft CLI, opencode additionally gets the following:

• the src-cli skill with a description and a CLI guide.
• (when inside a repository directory) information that the repository resides in SourceCraft and further instructions on how to use the repository and the CLI.

1. Create a new branch to address the issue you got in the previous step:

   git checkout -b feature/issue-2
   

2. Launch opencode in the repository:

   src code
   

3. One by one, submit natural-language requests to the AI agent, for example:

   Get a list of issues in the repository.
   

   The agent will use the SourceCraft CLI to fetch and display the issues.

   Implement the user's suggestion from issue #2 and test the code.
   

   The agent will plan actions, modify and test the code.

   Commit the changes, push to the remote repository, and create a pull request.
   

   The agent will use the SourceCraft CLI to create a pull request and return a link to it.

   Warning

   For more granular control over the agent's actions, you may choose not to request it to commit or push the changes but do it yourself instead.

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

4. Exit opencode:

   exit
   

   Tip

   You can also interact with your AI agent in headless mode without entering the dedicated terminal interface. Do it by running the src do command, for example:

   src do "Analyze the repository code, explain its structure and purpose.
   

5. Request the status of pull request checks for readiness to merge with the main branch:

   src pr checks <pull_request_ID>
   

   If no ID is specified, the command will display the check statuses for the pull request associated with the current git branch.

   Result:

   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:   -                                      
   

Use the AI skills

1. Launch an AI skill to review your pull request:

   src codereview
   

   If you are in a SourceCraft repository directory, the AI agent will try to find the pull request or compare the current branch against the main one, analyze the changes, and output the results into the terminal.

   Tip

   Other available commands are: src prdescription to generate a pull request description, and src skill to run custom skills.

   Try creating a custom skill as per the OpenCode guide or downloading a ready-made one running it using the src skill <skill_name> <arguments> command.

2. Merge your changes into the main branch:

   src pr merge <pull_request_ID>
   

   The pull request has been approved and merged into the main branch of the repository. To navigate to a branch from another pull request, use the src pr checkout command.

See also

• SourceCraft CLI reference
• SourceCraft CLI releases
• Code Assistant
• Working with the SourceCraft REST API
• OpenCode docs
• Viewing quotas in SourceCraft