CLI: Commands & Workflows
Once you have installed and authenticated the Codesphere CLI (cs), you can manage your infrastructure directly from your terminal. The CLI organizes its functionality into top-level commands.
This guide breaks down the available commands and demonstrates how to string them together into practical development workflows.
Available Commands
Below is a complete list of the available cs commands and their descriptions:
| Command | Description |
|---|---|
cs completion | Generate the autocompletion script for the specified shell (bash, zsh, fish, powershell) |
cs create | Create a Codesphere resource (e.g., workspaces, teams) |
cs curl | Send authenticated HTTP requests to a workspace's dev domain |
cs delete | Delete Codesphere resources |
cs exec | Run a command directly inside a Codesphere workspace |
cs generate | Generate Kubernetes artifacts based on your current workspace for exporting |
cs git | Interact with the git repository of the workspace |
cs help | Help about any command or subcommand |
cs licenses | Print license information |
cs list | List current resources and workloads |
cs log | Retrieve run logs from services for debugging |
cs monitor | Monitor a command and report back health and status information |
cs open | Open the target workspace within the Codesphere IDE |
cs set-env | Set or update environment variables |
cs start | Start a workspace pipeline (e.g., prepare or run stages) |
cs sync | Sync Codesphere resources |
cs update | Update the Codesphere CLI to the latest version |
cs version | Print the currently installed version of the CLI |
cs wake-up | Wake up an inactive or sleeping on-demand workspace |
Advanced Command Examples
Beyond basic CRUD operations, the CLI is designed to help you interact with your running environments.
Executing Remote Commands (cs exec)
You don't need to open the web IDE just to run a script or database migration. Use cs exec to run commands inside your workspace container.
Run a database migration script
cs exec "npm run migrate" -w <WORKSPACE_ID>
Check the current Node version inside the container
cs exec "node -v" -w <WORKSPACE_ID>
Shell Autocompletion
The cs CLI supports autocompletion for modern shells, saving you time and keystrokes when typing out workspace names or complex flags. You can generate the completion script using the cs completion command.
- Bash
- Zsh
- Fish
- PowerShell
To load completions in your current bash session:
source <(cs completion bash)
To make this persistent across all sessions, add the script to your ~/.bashrc:
echo "source <(cs completion bash)" >> ~/.bashrc
To load completions in your current zsh session:
source <(cs completion zsh)
To make this persistent, add it to your ~/.zshrc:
echo 'source <(cs completion zsh)' >> ~/.zshrc
To load completions in your current fish session:
cs completion fish | source
To make this persistent, write the output to your completions directory:
cs completion fish > ~/.config/fish/completions/cs.fish
To load completions in your current PowerShell session:
cs completion powershell | Out-String | Invoke-Expression
To make it persistent, add the output to your PowerShell profile.
Common Workflows
Here are a few ways to combine these commands for everyday tasks.
Remember that if you haven't set the CS_TEAM_ID or CS_WORKSPACE_ID globally, you must pass them to commands that require them using the --team (-t) and --workspace (-w) flags.
Provisioning & Bootstrapping
The primary use case for these commands is integrating Codesphere into your existing CI/CD pipelines (such as GitHub Actions, GitLab CI, or Bitbucket Pipelines). For example, you can automatically provision and deploy test environments triggered by specific Git events, like opening a pull request. When creating a new project, you can create the workspace, apply your secrets, and kick off the build process entirely from the command line:
Create a new workspace
cs create workspace --name "my-new-app" --team <TEAM_ID>
Inject necessary environment variables (e.g., database credentials)
cs set-env DB_PASSWORD=supersecret -w <WORKSPACE_ID>
Start the build/run Pipeline
cs start -w <WORKSPACE_ID>
Debugging a Running App
If an application is throwing errors in production or staging, you can investigate without using the web UI:
Find the ID of the workspace you want to debug
cs list workspaces -t <TEAM_ID>
Tail the logs of the service to spot the errors
cs log -w <WORKSPACE_ID>
Execute a command directly in the container to check file strategies
cs exec "cat /var/log/app-errors.log" -w <WORKSPACE_ID>
Cleanup & Teardown
To manage costs and keep your dashboard clean, list and delete old preview deployments or test environments:
1. Verify the resources currently running
cs list -t <TEAM_ID>
2. Delete the obsolete workspace
cs delete workspace -w <WORKSPACE_ID>