--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/cli-quickstart.md - https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/cli-quickstart.md --- > **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt # Getting started with the SourceCraft CLI _SourceCraft CLI_ (`src`) is your command line interface for the SourceCraft platform with a built-in [OpenCode](https://opencode.ai/docs/en) AI agent. `opencode` is preconfigured for access to [Code Assistant](https://sourcecraft.dev/portal/docs/en/code-assistant/index.md)'s large language models (LLMs) and features the tools you need to use the platform. {% note warning %} Code Assistant's agent mode in the SourceCraft CLI is subject to a fee; see [Pricing plans for Code Assistant](https://sourcecraft.dev/portal/docs/en/sourcecraft/pricing.md#ca-plans) for details. {% endnote %} With the SourceCraft CLI, you can manage [repositories](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#repos), [issues](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#issues), [pull requests](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#pr), 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](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/api-start.md). The SourceCraft CLI also offers convenient `git` authentication on the platform without the explicit use of [SSH keys](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md) or [PATs](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md). 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 to work](#preparation). 1. [Install the CLI](#install). 1. [Configure the CLI](#setup). 1. [Test CLI interaction with SourceCraft resources](#test). 1. [Test OpenCode](#opencode). 1. [Use the AI skills](#skills). ## Get ready to work {#preparation} 1. [Get authenticated](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/auth.md#sign-in) in SourceCraft. 1. [Install Git](https://git-scm.com/downloads). ## Install the SourceCraft CLI {#install} The SourceCraft CLI is installed via a script that: 1. Identifies your OS and architecture. 1. Downloads the executable with the latest stable CLI version for your environment. 1. Performs a health check. 1. Adds the CLI to the `PATH` environment variable. 1. Generates autocompletion settings. {% list tabs group=operating_system %} - macOS/Linux {#linux-macos} {% note warning %} Supported macOS versions: 12 [Monterey](https://en.wikipedia.org/wiki/MacOS_Monterey) or higher. {% endnote %} 1. In the terminal, run this command: ```bash curl -fsSL https://s3.yandexcloud.net/sourcecraft-cli/install.sh | sh ``` 1. After the installation is complete, restart the terminal: ```bash exec -l $SHELL ``` - Windows {#windows} 1. In PowerShell, run: ```powershell iex (New-Object System.Net.WebClient).DownloadString('https://s3.yandexcloud.net/sourcecraft-cli/install.ps1') ``` 1. After the installation is complete, restart PowerShell. {% endlist %} ## Configure the SourceCraft CLI {#setup} 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: ```bash 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](https://sourcecraft.dev/portal/docs/en/cli-ref/src-update.md) command. Result: ```bash Welcome to SourceCraft CLI! Let's get you set up. ``` {% note info %} To re-start interactive setup, use the [src init](https://sourcecraft.dev/portal/docs/en/cli-ref/src-init.md) command. {% endnote %} 1. Use the **↑**, **↓**, and **Enter** keys to choose where to store authentication credentials: ```bash 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 info %} 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. {% endnote %} 1. Select the authentication method in SourceCraft: ```bash Which authentication method would you like to use? > IAM (Recommended) Personal Access Token ``` Where: * `IAM`: Short-lived Yandex Cloud [IAM token](https://yandex.cloud/en/docs/iam/concepts/authorization/iam-token). The recommended and more secure method that uses browser-based authentication. * `Personal Access Token`: [PAT](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md). Suitable for browserless systems (e.g., VMs or WSL). {% note info %} 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. {% endnote %} 1. Confirm saving the settings: ```bash Save these settings? > Yes, save these settings No, cancel ``` 1. Optionally, set up the [git credential helper](https://git-scm.com/doc/credential-helpers), a tool for convenient `git` authentication in SourceCraft without explicit use of [SSH keys](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md) or PATs: ```bash Configure git credential helper? This allows git to automatically authenticate with SourceCraft. > Yes (Recommended) No ``` {% note tip %} If you skip the `git credential helper` setup, you can start it later using the [src auth setup-git](https://sourcecraft.dev/portal/docs/en/cli-ref/src-auth-setup-git.md) command. {% endnote %} 1. Optionally, confirm installation of [OpenCode](https://opencode.ai/docs/en): ```bash 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: ```bash ✓ 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. ``` 1. 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 {#test} ### View general info about SourceCraft CLI commands {#src-get-info} ```bash src --help ``` {% note tip %} To see the full reference, use the [src reference](https://sourcecraft.dev/portal/docs/en/cli-ref/src-reference.md) command. For more information, see the [SourceCraft CLI reference](https://sourcecraft.dev/portal/docs/en/cli-ref/src.md). {% endnote %} ### Get a list of repositories in the organization {#get-repo-list} ```bash src repo list ``` Result: ```bash 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 {#repo-clone} ```bash src clone / cd ``` ### Create an issue {#issue-create} 1. Run this command: ```bash src issue create ``` By default, all commands that create new entities run in interactive mode. 1. Enter a name for the issue: ```bash Create Issue Create a new issue in / Step 1 of 5 Issue Title A descriptive title for the issue (up to 1024 characters) > ``` 1. Enter a description for the issue. To finish input, use the keyboard shortcut **Ctrl** + **s**: ```bash Step 2 of 5 Description Detailed description of the issue 1 2 ``` 1. Specify priority: ```bash 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 ``` 1. Specify issue privacy: ```bash Step 4 of 5 Visibility ▸ Public Visible to everyone Private Only visible to repository members ``` 1. Confirm creating the issue: ```bash Step 5 of 5 Create Issue ▸ Yes No ``` This will display the full details of the new issue. ### Getting a list of issues {#get-issue-list} ```bash src issue list ``` {% note tip %} When you are in a directory containing a SourceCraft repository, by default the `src` commands will request info on resources in that exact repository. For info on a different repository, use the `--repo /` parameter. {% endnote %} Result: ```bash 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 {#get-issue-info} ```bash src issue get ``` Result: ```bash 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. ``` {% note tip %} To view info about a requested resource, e.g., an issue or repository, use the `--web` parameter in the SourceCraft UI. You can also output the info in JSON format using the `--json` parameter. You may find it useful if using the SourceCraft CLI for automation. {% endnote %} ## Test OpenCode in the SourceCraft CLI {#opencode} 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: ```bash git checkout -b feature/issue-2 ``` 1. Launch `opencode` in the repository: ```bash src code ``` The SourceCraft CLI provides default access to these LLMs: * `Default`: Main model in the Code Assistant LLM ensemble from Yandex AI Studio. * `Experimental`: Experimental reasoning model. * `Legacy`: Main model’s previous version. To switch between models: 1. Use the **Ctrl** + **P** keyboard shortcut. 1. Under **Agent**, click **Switch model** and select your preferred model. 1. One by one, submit natural-language requests to the AI agent, for example: ```text Get a list of issues in the repository. ``` The agent will use the SourceCraft CLI to fetch and display the issues. ```text Implement the user's suggestion from issue #2 and test the code. ``` The agent will plan actions, modify and test the code. ```text 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. {% note 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. ```bash git status git add . & git commit -m "added improvements according issue-2" & git push src pr create ``` {% endnote %} 1. Exit `opencode`: ```bash exit ``` {% note 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](https://sourcecraft.dev/portal/docs/en/cli-ref/src-do.md) command, for example: ```bash src do "Analyze the repository code, explain its structure and purpose. ``` {% endnote %} 1. Request the status of pull request checks for readiness to merge with the main branch: ```bash src pr checks ``` If no ID is specified, the command will display the check statuses for the pull request associated with the current `git` branch. Result: ```bash 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 {#skills} 1. Launch an [AI skill](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ai-skills.md) to review your pull request: ```bash 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. {% note tip %} Other available commands are: [src prdescription](https://sourcecraft.dev/portal/docs/en/cli-ref/src-prdescription.md) to [generate a pull request description](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/generate-description.md), and [src skill](https://sourcecraft.dev/portal/docs/en/cli-ref/src-skill.md) to run custom skills. Try creating a custom skill as per the [OpenCode guide](http://opencode.ai/docs/skills/) or downloading a [ready-made](https://skills.sh/) one running it using the `src skill ` command. {% endnote %} 1. Merge your changes into the main branch: ```bash src pr merge ``` 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](https://sourcecraft.dev/portal/docs/en/cli-ref/src-pr-checkout.md) command. #### Useful links {#see-also} * [SourceCraft CLI reference](https://sourcecraft.dev/portal/docs/en/cli-ref/src.md) * [SourceCraft CLI releases](https://sourcecraft.dev/portal/docs/en/sourcecraft/cli-release-notes.md) * [Code Assistant](https://sourcecraft.dev/portal/docs/en/code-assistant/index.md) * [Working with the SourceCraft REST API](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/api-start.md) * [OpenCode docs](https://opencode.ai/docs/en) * [Viewing quotas in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/view-quotas.md)