Skip to content

Commit ffe5ca7

Browse files
llewellyn-slclaude
llewellyn-sl
and
claude
committed
Fix CLI reference documentation issues
Resolved critical, important, and minor documentation issues across 15 CLI reference files based on comprehensive audit. ## Critical fixes - actions.md: Added missing --pipeline and -w options - credentials.md: Added Options tables for add/update commands - participants.md: Fixed type mismatch (COLLABORATOR vs MEMBER) - pipelines.md: Added missing repository URL parameter - studios.md: Fixed wrong command references and moved checkpoints example - teams.md: Added missing -t and -o options to members commands ## Important fixes - actions.md: Added supported event sources (github, tower) - data-links.md: Replaced placeholders with concrete dummy values - datasets.md: Completed tw datasets view versions with Options and example - launch.md: Clarified pipeline parameter (name vs Git URL) - studios.md: Removed duplicate tw studios templates section - workspaces.md: Removed duplicate sections and fixed ordering ## Minor fixes - actions.md: Sanitized example IDs to consistent format - collaborators.md: Fixed inconsistent ID sanitization - credentials.md: Replaced placeholders with realistic dummy examples - datasets.md: Added -w flag to example and updated output - labels.md: Added examples showing resource labels vs regular labels - pipelines.md: Added -w flag to example and updated output ## Global updates - Updated all workspace flag descriptions to mention personal workspace fallback - studios.md: Special handling for workspace flag (not available in personal workspaces) - Standardized workspace descriptions across all 13 CLI reference files Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
1 parent 70fa7c6 commit ffe5ca7

File tree

15 files changed

+261
-131
lines changed

15 files changed

+261
-131
lines changed

‎platform-cli-docs/docs/reference/actions.md‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ tw actions list [OPTIONS]
2424

2525
| Option | Description | Required | Default |
2626
|--------|-------------|----------|----------|
27-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
27+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
2828

2929
### Example
3030

@@ -42,7 +42,7 @@ Example output:
4242

4343
ID | Name | Endpoint | Status | Source
4444
------------------------+-------+-----------------------------------------------------------------------------------------------+--------+--------
45-
1a2b3c4d5e6f7g8h9i0j1k | Testy | https://api.cloud.seqera.io/actions/1a2b3c4d5e6f7g8h9i0j1k/launch?workspaceId=123456789012345 | ACTIVE | tower
45+
2b3c4d5e6f7g8h | Testy | https://api.cloud.seqera.io/actions/2b3c4d5e6f7g8h/launch?workspaceId=123456789012345 | ACTIVE | tower
4646
```
4747

4848
## tw actions view
@@ -59,7 +59,7 @@ tw actions view [OPTIONS]
5959
|--------|-------------|----------|----------|
6060
| `-i`, `--id` | Action unique identifier | No | `null` |
6161
| `-n`, `--name` | Action name | No | `null` |
62-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
62+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
6363

6464
### Example
6565

@@ -76,12 +76,12 @@ Details for action 'Testy'
7676

7777

7878
--------------+-------------------------------------------------------------------
79-
ID | 1a2b3c4d5e6f7g8h9i0j1k
79+
ID | 2b3c4d5e6f7g8h
8080
Name | Testy
8181
Status | ACTIVE
8282
Pipeline URL | https://github.com/nextflow-io/rnaseq-nf
8383
Source | tower
84-
Hook URL | https://api.cloud.seqera.io/actions/1a2b3c4d5e6f7g8h9i0j1k/launch
84+
Hook URL | https://api.cloud.seqera.io/actions/2b3c4d5e6f7g8h/launch
8585
Last event | never
8686
Date created | Tue, 10 Jun 2025 09:02:12 GMT
8787
Last event | never
@@ -116,13 +116,20 @@ Run `tw actions add -h` to view the list of supported event sources.
116116

117117
Run `tw actions add <source> -h` to view the required and optional fields for your event source.
118118

119+
:::note
120+
Supported event sources:
121+
- **tower**: Manual webhook trigger via Platform UI or API
122+
- **github**: GitHub webhook events (push, pull request, etc.)
123+
:::
124+
119125
### Options
120126

121127
| Option | Description | Required | Default |
122128
|--------|-------------|----------|----------|
123129
| `-n`, `--name` | Action name. Must be unique per workspace. Names consist of alphanumeric, hyphen, and underscore characters. | Yes | `null` |
130+
| `--pipeline` | Pipeline repository URL. Must be a full Git repository URL (e.g., https://github.com/nextflow-io/hello). | Yes | `null` |
124131
| `-i`, `--id` | Action unique identifier | No | `null` |
125-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
132+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format. Required if `TOWER_WORKSPACE_ID` environment variable is not set. | Yes* | `TOWER_WORKSPACE_ID` |
126133
| `-c`, `--compute-env` | Compute environment identifier where the pipeline will run. Defaults to workspace primary compute environment if omitted. Provide the name or identifier. | No | `null` |
127134
| `--work-dir` | Work directory path where workflow intermediate files are stored. Defaults to compute environment work directory if omitted. | No | `null` |
128135
| `-p`, `--profile` | Array of Nextflow configuration profile names to apply. | No | `null` |
@@ -173,7 +180,7 @@ tw actions update [OPTIONS]
173180
| `--new-name` | Updated action name. Must be unique per workspace. Names consist of alphanumeric, hyphen, and underscore characters. | No | `null` |
174181
| `-i`, `--id` | Action unique identifier | No | `null` |
175182
| `-n`, `--name` | Action name | No | `null` |
176-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
183+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
177184
| `-c`, `--compute-env` | Compute environment identifier where the pipeline will run. Defaults to workspace primary compute environment if omitted. Provide the name or identifier. | No | `null` |
178185
| `--work-dir` | Work directory path where workflow intermediate files are stored. Defaults to compute environment work directory if omitted. | No | `null` |
179186
| `-p`, `--profile` | Array of Nextflow configuration profile names to apply. | No | `null` |
@@ -218,7 +225,7 @@ tw actions delete [OPTIONS]
218225
|--------|-------------|----------|----------|
219226
| `-i`, `--id` | Action unique identifier | No | `null` |
220227
| `-n`, `--name` | Action name | No | `null` |
221-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
228+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
222229

223230
### Example
224231

@@ -248,6 +255,7 @@ tw actions labels [OPTIONS]
248255
|--------|-------------|----------|----------|
249256
| `-i`, `--id` | Action unique identifier | No | `null` |
250257
| `-n`, `--name` | Action name | No | `null` |
258+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | Personal workspace |
251259
| `--no-create` | Assign labels without creating the ones which were not found. | No | `null` |
252260
| `--operations`, `-o` | Type of operation (set, append, delete) [default: set]. | No | `set` |
253261

@@ -262,7 +270,7 @@ tw actions labels -n Testy -w 123456789012345 test-environment,label2
262270
Example output:
263271

264272
```bash
265-
'set' labels on 'action' with id '1a2b3c4d5e6f7g8h9i0j1k' at 123456789012345 workspace
273+
'set' labels on 'action' with id '2b3c4d5e6f7g8h' at 123456789012345 workspace
266274
```
267275

268276
:::note

‎platform-cli-docs/docs/reference/collaborators.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,13 @@ tw collaborators list -o seqeralabs
3838
Example output:
3939

4040
```bash
41-
Collaborators for 88848180287xxx organization:
41+
Collaborators for 888481802873456 organization:
4242

4343
ID | Username | Email
4444
-----------------+----------------------+--------------------
45-
13136942731xxx | external_user1 | user1@domain.com
46-
127726720173xxx | external_user2 | user2@domain.com
47-
59151157784xxx | external_user3 | user3@domain.com
48-
132868466675xxx | external_user4 | user4@domain.com
49-
178756942629xxx | external_user5 | user5@domain.com
45+
131369427314567 | external_user1 | user1@domain.com
46+
127726720173456 | external_user2 | user2@domain.com
47+
591511577845678 | external_user3 | user3@domain.com
48+
132868466675789 | external_user4 | user4@domain.com
49+
178756942629012 | external_user5 | user5@domain.com
5050
```

‎platform-cli-docs/docs/reference/compute-envs.md‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ tw compute-envs update [OPTIONS]
6767
| `--new-name` | New compute environment name. | No | `null` |
6868
| `-i`, `--id` | Compute environment unique identifier. | No | `null` |
6969
| `-n`, `--name` | Compute environment name. | No | `null` |
70-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
70+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
7171

7272
### Example
7373

@@ -97,7 +97,7 @@ tw compute-envs delete [OPTIONS]
9797
|--------|-------------|----------|---------|
9898
| `-i`, `--id` | Compute environment unique identifier. | No | `null` |
9999
| `-n`, `--name` | Compute environment name. | No | `null` |
100-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
100+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
101101

102102
### Example
103103

@@ -127,7 +127,7 @@ tw compute-envs view [OPTIONS]
127127
|--------|-------------|----------|---------|
128128
| `-i`, `--id` | Compute environment unique identifier. | No | `null` |
129129
| `-n`, `--name` | Compute environment name. | No | `null` |
130-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
130+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
131131

132132
### Example
133133

@@ -194,7 +194,7 @@ tw compute-envs list [OPTIONS]
194194

195195
| Option | Description | Required | Default |
196196
|--------|-------------|----------|---------|
197-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
197+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
198198

199199
### Example
200200

@@ -235,7 +235,7 @@ tw compute-envs export [OPTIONS]
235235
|--------|-------------|----------|---------|
236236
| `-i`, `--id` | Compute environment unique identifier. | No | `null` |
237237
| `-n`, `--name` | Compute environment name. | No | `null` |
238-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
238+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
239239

240240
### Example
241241

@@ -256,14 +256,18 @@ Example output:
256256
Import a compute environment configuration from a JSON file.
257257

258258
```bash
259-
tw compute-envs import [OPTIONS]
259+
tw compute-envs import [OPTIONS] <path/to/json-file>
260260
```
261261

262262
### Options
263263

264264
| Option | Description | Required | Default |
265265
|--------|-------------|----------|---------|
266+
| `-n`, `--name` | Name for the imported compute environment. | Yes | `null` |
267+
| `-c`, `--credentials` | Credentials identifier to use when multiple credentials match the compute environment. Use this to specify which credentials should be associated with the imported compute environment. | No | `null` |
268+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
266269
| `--overwrite` | Overwrite the compute environment if it already exists. | No | `false` |
270+
| `<path/to/json-file>` | Path to the JSON file containing the compute environment configuration (exported using `tw compute-envs export`). | Yes | `null` |
267271

268272
### Example
269273

@@ -279,6 +283,10 @@ Example output:
279283
New AWS-CLOUD compute environment 'example-imported-ce' added at [my-organization / my-workspace] workspace
280284
```
281285

286+
:::note
287+
If multiple credentials match the imported compute environment, you must provide the `-c` flag with the credentials identifier to specify which credentials to use. You can find available credentials using `tw credentials list`.
288+
:::
289+
282290
## tw compute-envs primary
283291

284292
Manage the primary compute environment.
@@ -299,7 +307,7 @@ tw compute-envs primary get [OPTIONS]
299307

300308
| Option | Description | Required | Default |
301309
|--------|-------------|----------|---------|
302-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
310+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
303311

304312
### Example
305313

@@ -329,7 +337,7 @@ tw compute-envs primary set [OPTIONS]
329337
|--------|-------------|----------|---------|
330338
| `-i`, `--id` | Compute environment unique identifier. | No | `null` |
331339
| `-n`, `--name` | Compute environment name. | No | `null` |
332-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
340+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
333341

334342
### Example
335343

‎platform-cli-docs/docs/reference/credentials.md‎

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,22 @@ To launch pipelines in a Platform workspace, you need [credentials](https://docs
1717
Add workspace credentials.
1818

1919
```bash
20-
tw credentials add [OPTIONS]
20+
tw credentials add <provider> [OPTIONS]
2121
```
2222

2323
Run `tw credentials add -h` to view a list of providers.
2424

2525
Run `tw credentials add <provider> -h` to view the required fields for your provider.
2626

27+
### Common Options
28+
29+
| Option | Description | Required | Default |
30+
|--------|-------------|----------|---------|
31+
| `-n`, `--name` | Credentials name. Must be unique per workspace. | Yes | `null` |
32+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | Personal workspace |
33+
2734
:::note
28-
You can add multiple credentials from the same provider in the same workspace.
35+
Additional provider-specific options are required depending on the provider type. Use `tw credentials add <provider> -h` to see all available options for your provider. You can add multiple credentials from the same provider in the same workspace.
2936
:::
3037

3138
### Compute environment credentials
@@ -35,7 +42,7 @@ Platform requires credentials to access your cloud compute environments. See the
3542
Command:
3643

3744
```bash
38-
tw credentials add aws --name=my_aws_creds --access-key=<aws access key> --secret-key=<aws secret key>
45+
tw credentials add aws --name=my_aws_creds --access-key=AKIAIOSFODNN7EXAMPLE --secret-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
3946
```
4047

4148
Example output:
@@ -51,7 +58,7 @@ Platform requires access credentials to interact with pipeline Git repositories.
5158
Command:
5259

5360
```bash
54-
tw credentials add github -n=my_GH_creds -u=<GitHub username> -p=<GitHub access token>
61+
tw credentials add github -n=my_GH_creds -u=my-github-user -p=ghp_exampletoken1234567890abcdefghij
5562
```
5663

5764
Example output:
@@ -71,7 +78,7 @@ Container registry credentials are only used by the Wave container service. See
7178
Command:
7279

7380
```bash
74-
tw credentials add container-reg --name=my_registry_creds --username=<registry username> --password=<registry password> --registry=docker.io
81+
tw credentials add container-reg --name=my_registry_creds --username=my-registry-user --password=my-secure-password-123 --registry=docker.io
7582
```
7683

7784
Example output:
@@ -85,13 +92,25 @@ New CONTAINER-REG credentials 'my_registry_creds (2tyCywygy9yoyeyHyRyryI)' added
8592
Update workspace credentials.
8693

8794
```bash
88-
tw credentials update [OPTIONS]
95+
tw credentials update <provider> [OPTIONS]
8996
```
9097

9198
Run `tw credentials update -h` to view a list of providers.
9299

93100
Run `tw credentials update <provider> -h` to view the required fields for your provider.
94101

102+
### Common Options
103+
104+
| Option | Description | Required | Default |
105+
|--------|-------------|----------|---------|
106+
| `-i`, `--id` | Credentials unique identifier | No | `null` |
107+
| `-n`, `--name` | Credentials name | No | `null` |
108+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | Personal workspace |
109+
110+
:::note
111+
Additional provider-specific options vary depending on the provider type. Use `tw credentials update <provider> -h` to see all available options for your provider. Either credentials ID (`-i`) or name (`-n`) is required to identify which credentials to update.
112+
:::
113+
95114
### Example
96115

97116
Command:
@@ -120,7 +139,7 @@ tw credentials delete [OPTIONS]
120139
|--------|-------------|----------|---------|
121140
| `-i`, `--id` | Credentials unique identifier | No | `null` |
122141
| `-n`, `--name` | Credentials name | No | `null` |
123-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
142+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
124143

125144
### Example
126145

@@ -148,7 +167,7 @@ tw credentials list [OPTIONS]
148167

149168
| Option | Description | Required | Default |
150169
|--------|-------------|----------|---------|
151-
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable) | No | `TOWER_WORKSPACE_ID` |
170+
| `-w`, `--workspace` | Workspace numeric identifier or reference in OrganizationName/WorkspaceName format (defaults to `TOWER_WORKSPACE_ID` environment variable, or personal workspace if not set) | No | `TOWER_WORKSPACE_ID` |
152171

153172
### Example
154173

0 commit comments

Comments
 (0)