Skip to content

Commit f594cd0

Browse files
NautiluXNautiluX
committed
Add usage docs to README
Signed-off-by: Manuel Dewald <manuel@codesphere.com>
1 parent d2975f5 commit f594cd0

File tree

1 file changed

+155
-12
lines changed

1 file changed

+155
-12
lines changed

‎README.md‎

Lines changed: 155 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
2-
![GitHub Workflow Status](https://github.com/codesphere-cloud/cs-go/actions/workflows/build.yml/badge.svg)
2+
[![GitHub Workflow Status](https://github.com/codesphere-cloud/cs-go/actions/workflows/build.yml/badge.svg)](https://github.com/codesphere-cloud/cs-go/actions/workflows/build.yml/badge.svg)
33

44
# Codesphere Go SDK & CLI
55

6-
Seemlessly integrate CS into your local development flow.
6+
Seamlessly integrate CS into your local development flow.
77

88
## License
99

@@ -13,30 +13,173 @@ This project is licensed under the Apache License, Version 2.0 - see the [LICENS
1313

1414
### Installation
1515

16+
You can install the Codesphere CLI in a few ways:
17+
18+
#### Using GitHub CLI (`gh`)
19+
20+
If you have the [GitHub CLI](https://cli.github.com/) installed, you can install the `cs` CLI with a command like the following:
21+
22+
##### ARM Mac
23+
1624
```
17-
make install
25+
gh release download -R codesphere-cloud/cs-go -o cs -D /usr/local/bin/cs -p *darwin_arm64
26+
chmod +x /usr/local/bin/cs
1827
```
1928

20-
### Usage
29+
##### Linux Amd64
2130

2231
```
23-
$ cs log -w <workspace_id>
32+
gh release download -R codesphere-cloud/cs-go -o cs -D /usr/local/bin/cs -p *linux_amd4
33+
chmod +x /usr/local/bin/cs
2434
```
2535

26-
### Environment variables
36+
#### Manual Download
37+
38+
You can also download the pre-compiled binaries from the [Codesphere CLI Releases page](https://github.com/codesphere-cloud/cs-go/releases).
39+
40+
1. Go to the [latest release](https://github.com/codesphere-cloud/cs-go/releases/latest).
41+
42+
2. Download the appropriate release for your operating system and architecture (e.g., `cs-go_darwin_amd64` for macOS, `cs-go_linux_amd64` for Linux, or `cs-go_windows_amd64` for Windows).
43+
44+
3. Move the `cs` binary to a directory in your system's `PATH` (e.g., `/usr/local/bin` on Linux/Mac, or a directory added to `Path` environment variable on Windows).
45+
46+
4. Make the binary executable (e.g. by running `chmod +x /usr/local/bin/cs` on Mac or Linux)
47+
48+
### Usage Guide
49+
50+
The Codesphere CLI (`cs`) allows you to manage and debug resources deployed in Codesphere directly from your command line.
51+
52+
#### Global Options & Environment Variables
53+
54+
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.
55+
56+
| Option | Flag | Environment Variable | Description | Default |
57+
| ----- | ----- | ----- | ----- | ----- |
58+
| API URL | `--api`, `-a` | `CS_API` | URL of the Codesphere API. | `https://codesphere.com/api` |
59+
| Team ID | `--team`, `-t` | `CS_TEAM_ID` | Your Codesphere Team ID. This is relevant for commands operating on a specific team. | None (required for some commands) |
60+
| Workspace ID | `--workspace`, `-w` | `CS_WORKSPACE_ID` | Your Codesphere Workspace ID. Relevant for commands targeting a specific workspace. | None (required for some commands) |
61+
62+
**Note on Team ID and Workspace 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`). If they're still not found and a command requires them, the CLI will return an error.
63+
64+
#### Available Commands
65+
66+
The `cs` CLI organizes its functionality into several top-level commands, each with specific subcommands and flags.
67+
68+
##### `cs list`
69+
70+
Use this command to list various resources available in Codesphere.
71+
72+
**Usage:**
2773

2874
```
29-
CS_TOKEN - API token, generate in UI
30-
CS_WORKSPACE_ID - workspace ID to target, get from environment in Web IDE
31-
CS_API - API url of codesphere, defaults to https://codesphere.com/api
75+
cs list [command]
76+
3277
```
3378

34-
## Go SDK
79+
###### `cs list teams`
80+
81+
Lists all teams you have access to in Codesphere.
82+
83+
**Usage:**
84+
85+
```
86+
cs list teams
87+
88+
```
89+
90+
**Example:**
91+
92+
```
93+
$ cs list teams
3594
95+
```
96+
97+
###### `cs list workspaces`
98+
99+
Lists all workspaces available in Codesphere.
100+
101+
**Usage:**
102+
103+
```
104+
cs list workspaces [--team-id <team-id>]
105+
```
106+
107+
**Example:**
36108

109+
```
110+
$ cs list workspaces --team-id <team-id>
111+
```
112+
113+
If you don't specify `--team-id`, the command will try to list workspaces for all teams you can access (or for the team specified by `CS_TEAM_ID`).
114+
115+
##### `cs log`
116+
117+
Retrieves run logs from services within your workspaces.
118+
119+
**Usage:**
120+
121+
```
122+
cs log --workspace-id <workspace-id> [options]
123+
```
124+
125+
**Description:**
126+
127+
You can retrieve logs based on the given scope. If you provide both the step number and server, it returns all logs from all replicas of that server. If you provide a specific replica ID, it will return logs for that replica only.
128+
129+
**Examples:**
130+
131+
```
132+
# Get logs from a specific server within a workspace
133+
$ cs log -w 637128 -s app
134+
135+
# Get all logs from all servers in a workspace
136+
$ cs log -w 637128
137+
138+
# Get logs from a specific replica
139+
$ cs log -w 637128 -r workspace-213d7a8c-48b4-42e2-8f70-c905ab04abb5-58d657cdc5-m8rrp
140+
141+
# Get logs from a self-hosted Codesphere installation (using a custom API URL)
142+
$ cs log --api https://codesphere.acme.com/api -w 637128 -s app
143+
```
144+
145+
**Flags:**
146+
147+
* `--server`, `-s` (string): Name of the landscape server.
148+
149+
* `--workspace-id`, `-w` (int): ID of your Codesphere workspace. You can also set this via the `CS_WORKSPACE_ID` environment variable. **This flag or environment variable is required if not set globally.**
150+
151+
* `--step`, `-n` (int): Index of the execution step (default 0).
152+
153+
* `--replica`, `-r` (string): ID of the server replica. If you provide this, the `--server` flag will be ignored.
154+
155+
##### `cs set-env`
156+
157+
Sets environment variables for your workspace.
158+
159+
**Usage:**
160+
161+
```
162+
cs set-env --workspace-id <workspace-id> --env <key>=<value> [--env <key2>=<key2> ...]
163+
164+
165+
```
166+
167+
**Example:**
168+
169+
```
170+
# Set environment variables for a specific workspace
171+
$ cs set-env --workspace-id <workspace-id> --env foo=bar --env hello=world
172+
173+
174+
```
175+
176+
**Flags:**
177+
178+
* `--env-var`, `-e` (stringArray): Environment variables to set, in the format `key=val`. You can use this flag multiple times to set several variables.
179+
180+
## Go SDK
37181

38182
## Community & Contributions
39183

40-
Please review our [Code of Conduct](CODE_OF_CONDUCT.md) to understand our community expectations.
184+
Please review our [Code of Conduct](CODE_OF_CONDUCT.md) to understand our community expectations.
41185
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](CONTRIBUTING.md) for details.
42-

0 commit comments

Comments
 (0)