Codesphere Go SDK & CLI
Seamlessly integrate CS into your local development flow.
License
This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.
CLI
Installation
You can install the Codesphere CLI in a few ways:
Install inside a Codesphere Workspace
To use the CLI inside a Codesphere workspace, install it using the following command:
mkdir -p $HOME/.local/bin && wget -qO- 'https://api.github.com/repos/codesphere-cloud/cs-go/releases/latest' | grep linux_amd64 | grep browser_download_url | sed s/.*https/https/ | sed s/\".*$// | xargs wget -O $HOME/.local/bin/cs && chmod +x $HOME/.local/bin/cs
Using GitHub CLI (gh)
If you have the GitHub CLI installed, you can install the cs CLI with a command like the following.
Note that some commands may require you to elevate to the root user with sudo.
ARM Mac
gh release download -R codesphere-cloud/cs-go -O /usr/local/bin/cs -p "*darwin_arm64"
chmod +x /usr/local/bin/cs
Linux Amd64
gh release download -R codesphere-cloud/cs-go -O /usr/local/bin/cs -p "*linux_amd64"
chmod +x /usr/local/bin/cs
Using wget
This option requires to have the wget and jq utils installed. Download the cs CLI and add permissions to run it with the following commands:
Note that some commands may require you to elevate to the root user with sudo.
ARM Mac
wget -qO- 'https://api.github.com/repos/codesphere-cloud/cs-go/releases/latest' | jq -r '.assets[] | select(.name | match("darwin_arm64")) | .browser_download_url' | xargs wget -O cs
mv cs /usr/local/bin/cs
chmod +x /usr/local/bin/cs
Linux Amd64
wget -qO- 'https://api.github.com/repos/codesphere-cloud/cs-go/releases/latest' | jq -r '.assets[] | select(.name | match("linux_amd64")) | .browser_download_url' | xargs wget -O cs
mv cs /usr/local/bin/cs
chmod +x /usr/local/bin/cs
Manual Download
You can also download the pre-compiled binaries from the Codesphere CLI Releases page.
Note that some commands may require you to elevate to the root user with sudo.
-
Go to the latest release.
-
Download the appropriate release for your operating system and architecture (e.g.,
cs-go_darwin_amd64for macOS,cs-go_linux_amd64for Linux, orcs-go_windows_amd64for Windows). -
Move the
csbinary to a directory in your system'sPATH(e.g.,/usr/local/binon Linux/Mac, or a directory added toPathenvironment variable on Windows). -
Make the binary executable (e.g. by running
chmod +x /usr/local/bin/cson Mac or Linux)
Usage Guide
The Codesphere CLI (cs) allows you to manage and debug resources deployed in Codesphere directly from your command line.
Global Options & Environment Variables
The cs CLI supports several global options that you can set via command-line flags or environment variables. Using environment variables is handy for setting persistent configurations.≥
Note on Team ID, Workspace ID and Organization ID: If you don't provide these via a flag, the CLI will try to get them from the corresponding environment variables (CS_TEAM_ID, CS_WORKSPACE_ID, CS_ORG_ID). If they're still not found and a command requires them, the CLI will return an error.
Available Commands
The cs CLI organizes its functionality into several top-level commands, each with specific subcommands and flags.
See our Usage Documentation for usage information about the specific subcommands.
Codesphere MCP Server
The CLI includes the official Codesphere MCP server. It lets AI assistants such as Claude, Cursor or VS Code manage your Codesphere workspaces, pipelines, domains and teams via the Model Context Protocol. Add it to your MCP client configuration:
{
"mcpServers": {
"codesphere": {
"command": "cs",
"args": ["mcp"],
"env": {
"CS_TOKEN": "your-api-token-here"
}
}
}
}
See the Codesphere MCP Server documentation for setup instructions per client and the full list of available tools.
Development
Running Tests
The project has both unit tests and integration tests:
Unit Tests
Run unit tests for the API, CLI, and package code:
make test
Integration Tests
Integration tests verify the CLI works correctly against live Codesphere environments. These tests require valid credentials and will create/delete real workspaces.
Prerequisites:
CS_TOKEN- Your Codesphere API tokenCS_TEAM_ID- Your team IDCS_ORG_ID- Your Organization ID
Run integration tests:
make test-int
Go SDK
Community & Contributions
Please review our Code of Conduct to understand our community expectations. We welcome contributions! All contributions to this project must be made in accordance with the Developer Certificate of Origin (DCO). See our full Contributing Guidelines for details.