Getting Started: CLI

The Codesphere CLI (cs) allows you to seamlessly integrate Codesphere into your local development flow. You can manage and debug resources deployed in Codesphere directly from your command line.

info

The CLI is open-source! You can view the source code, open issues for bugs or feature requests, and contribute to the project directly on our GitHub repository.

---

Installation

You can install the Codesphere CLI in a few ways depending on your environment.

Codesphere Workspace

The Codesphere CLI is pre-installed in all Codesphere workspaces. You can start using the cs command directly from your workspace terminal.

Mac (ARM)

If you have the GitHub CLI (gh) installed, you can download and install the CLI on an ARM Mac using:

gh release download -R codesphere-cloud/cs-go -O /usr/local/bin/cs -p "*darwin_arm64"
chmod +x /usr/local/bin/cs

(Note: You may need to use sudo to write to /usr/local/bin).

Linux (Amd64)

To install via the GitHub CLI on Linux:

gh release download -R codesphere-cloud/cs-go -O /usr/local/bin/cs -p "*linux_amd64"
chmod +x /usr/local/bin/cs

Manual Download

You can also manually download the pre-compiled binaries for macOS, Linux, or Windows directly from the Codesphere CLI Releases page.

---

Authentication & Configuration

Before you can run commands, you need to authenticate the CLI with your Codesphere account.

The codesphere CLI relies on global environment variables or command-line flags for configuration. Setting environment variables is the recommended approach for persistent configurations.

Global Variables & Flags

Learn how to use the codesphere API

• API Token (Required): You must generate a Codesphere API token from your user settings at https://codesphere.com/ and set it as the CS_TOKEN environment variable.
• API URL: Determines the target API. By default, this is https://codesphere.com/api.
  • Flag: --api or -a.
  • Env Var: CS_API.
• Team ID: Required for commands operating on a specific team.
  • Flag: --team or -t.
  • Env Var: CS_TEAM_ID.
• Workspace ID: Required for commands targeting a specific workspace.
  • Flag: --workspace or -w.
  • Env Var: CS_WORKSPACE_ID.

Variable Resolution

If you do not explicitly provide the Team ID or Workspace ID via a flag, the CLI will automatically attempt to read them from CS_TEAM_ID and CS_WORKSPACE_ID. If a command requires them and they are missing, the CLI will return an error.

Discovering Commands

You can always get a full list of available commands and learn how to use them by typing cs --help in your terminal.

---