From 70346a12597074a022daf65f12b0d7f023f6ae49 Mon Sep 17 00:00:00 2001
From: Cristian Ramon-Cortes <cristian.ramon-cortes@seqera.io>
Date: Mon, 5 Oct 2026 17:46:16 +0200
Subject: [PATCH 1/7] feat(studios): mount data-link folders

DataStudioConfiguration.mountDataV2 (platform API 1.114.0, platform
commit ac72147bb3; first in the published spec at 1.145.0) mounts a data
link with an optional sub-path, and the platform gives it precedence over
the deprecated mountData. The UI now sends only mountDataV2, and studio
descriptions return both fields, so 'tw studios start|update|add-as-new'
with a mount option sent a new mountData while the fetched mountDataV2
still held the old mounts: the platform kept the old mounts and silently
ignored the change.

tw now always sends mountDataV2 (plus mountData for older platforms)
when a mount option is given. '--mount-data-uris' also accepts a URI
inside a data link: tw resolves the closest parent data link and mounts
the remainder as the path, which is what the UI's folder picker does.
'studios view' prints the mounted path.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../commands/data/links/DataLinkService.java  | 58 ++++++++----
 .../commands/studios/AbstractStudiosCmd.java  | 15 ++-
 .../commands/studios/DataLinkRefOptions.java  |  2 +-
 .../cli/responses/studios/StudiosView.java    | 26 +++++-
 .../tower/cli/studios/StudiosCmdTest.java     | 93 +++++++++++++++++++
 5 files changed, 169 insertions(+), 25 deletions(-)

diff --git a/src/main/java/io/seqera/tower/cli/commands/data/links/DataLinkService.java b/src/main/java/io/seqera/tower/cli/commands/data/links/DataLinkService.java
index 9a32b8100..233e37400 100644
--- a/src/main/java/io/seqera/tower/cli/commands/data/links/DataLinkService.java
+++ b/src/main/java/io/seqera/tower/cli/commands/data/links/DataLinkService.java
@@ -16,8 +16,8 @@
 
 package io.seqera.tower.cli.commands.data.links;
 
-import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
 
@@ -30,6 +30,7 @@
 import io.seqera.tower.cli.exceptions.TowerRuntimeException;
 import io.seqera.tower.cli.utils.ResponseHelper;
 import io.seqera.tower.model.DataLinkDto;
+import io.seqera.tower.model.MountData;
 
 public class DataLinkService  {
 
@@ -114,10 +115,10 @@ public DataLinkDto getDataLink(DataLinkRefOptions.DataLinkRef dataLinkRef, Long
         return null;
     }
 
-    public List<String> getDataLinkIds(io.seqera.tower.cli.commands.studios.DataLinkRefOptions.DataLinkRef dataLinkRef, Long wspId) {
+    public List<MountData> getMountData(io.seqera.tower.cli.commands.studios.DataLinkRefOptions.DataLinkRef dataLinkRef, Long wspId) {
         // if DataLink IDs are supplied - use those directly
         if (dataLinkRef.getMountDataIds() != null) {
-            return dataLinkRef.getMountDataIds();
+            return dataLinkRef.getMountDataIds().stream().map(id -> new MountData().dataLinkId(id)).collect(Collectors.toList());
         }
 
         // Check and wait if DataLinks are still being fetched
@@ -126,21 +127,37 @@ public List<String> getDataLinkIds(io.seqera.tower.cli.commands.studios.DataLink
             throw new TowerRuntimeException("Failed to fetch datalinks for mountData - please retry.");
         }
 
-        List<String> dataLinkIds = new ArrayList<>();
-
         if (dataLinkRef.getMountDataNames() != null) {
-            dataLinkIds = dataLinkRef.getMountDataNames().stream()
-                    .map(name -> getDataLinkByName(wspId, null, name).getId())
+            return dataLinkRef.getMountDataNames().stream()
+                    .map(name -> new MountData().dataLinkId(getDataLinkByName(wspId, null, name).getId()))
                     .collect(Collectors.toList());
         }
 
-        if (dataLinkRef.getMountDataUris() != null) {
-            dataLinkIds = dataLinkRef.getMountDataUris().stream()
-                    .map(resourceRef -> getDataLinkByResourceRef(wspId, null, resourceRef).getId())
-                    .collect(Collectors.toList());
-        }
+        return dataLinkRef.getMountDataUris().stream()
+                .map(uri -> getMountDataByUri(wspId, uri))
+                .collect(Collectors.toList());
+    }
 
-        return dataLinkIds;
+    /**
+     * Resolves a URI to the data link whose resource reference is the URI itself or its closest parent,
+     * so that a folder inside a data link can be mounted (the remainder becomes the mount path).
+     */
+    private MountData getMountDataByUri(Long wspId, String uri) {
+        String target = uri.endsWith("/") ? uri.substring(0, uri.length() - 1) : uri;
+        int rootEnd = target.indexOf("://") + 2;
+        String candidate = target;
+        while (true) {
+            Optional<DataLinkDto> dataLink = findDataLinkByResourceRef(wspId, candidate);
+            if (dataLink.isPresent()) {
+                MountData mountData = new MountData().dataLinkId(dataLink.get().getId());
+                return candidate.equals(target) ? mountData : mountData.path(target.substring(candidate.length() + 1));
+            }
+            int parentEnd = candidate.lastIndexOf('/');
+            if (parentEnd <= rootEnd) {
+                throw new DataLinkNotFoundException(getResourceRefKeywordParam(uri), wspId);
+            }
+            candidate = candidate.substring(0, parentEnd);
+        }
     }
 
     private DataLinkDto getDataLinkByName(Long wspId, String credId, String name) {
@@ -151,21 +168,26 @@ private DataLinkDto getDataLinkByResourceRef(Long wspId, String credId, String r
         return getDataLinkBySearchAndFindExactMatch(wspId, getResourceRefKeywordParam(resourceRef), credId, datalink -> resourceRef.equals(datalink.getResourceRef()));
     }
 
+    private Optional<DataLinkDto> findDataLinkByResourceRef(Long wspId, String resourceRef) {
+        return findDataLinkBySearchAndExactMatch(wspId, getResourceRefKeywordParam(resourceRef), null, datalink -> resourceRef.equals(datalink.getResourceRef()));
+    }
+
     private DataLinkDto getDataLinkBySearchAndFindExactMatch(Long wspId, String search, String credId, Predicate<DataLinkDto> filter) {
+        return findDataLinkBySearchAndExactMatch(wspId, search, credId, filter)
+                .orElseThrow(() -> new DataLinkNotFoundException(search, wspId));
+    }
+
+    private Optional<DataLinkDto> findDataLinkBySearchAndExactMatch(Long wspId, String search, String credId, Predicate<DataLinkDto> filter) {
         var datalinks = getDataLinksBySearchCriteria(wspId, search, credId).stream()
                 .filter(filter)
                 .collect(Collectors.toList());
 
-        if (datalinks.isEmpty()) {
-            throw new DataLinkNotFoundException(search, wspId);
-        }
-
         if (datalinks.size() > 1) {
             var dataLinkIds = datalinks.stream().map(DataLinkDto::getId).collect(Collectors.toList());
             throw new MultipleDataLinksFoundException(search, wspId, dataLinkIds);
         }
 
-        return datalinks.get(0);
+        return datalinks.stream().findFirst();
     }
 
     private DataLinkDto getDataLinkById(String dataLinkId, Long wspId, String credId) {
diff --git a/src/main/java/io/seqera/tower/cli/commands/studios/AbstractStudiosCmd.java b/src/main/java/io/seqera/tower/cli/commands/studios/AbstractStudiosCmd.java
index 093eca991..55daba69e 100644
--- a/src/main/java/io/seqera/tower/cli/commands/studios/AbstractStudiosCmd.java
+++ b/src/main/java/io/seqera/tower/cli/commands/studios/AbstractStudiosCmd.java
@@ -40,6 +40,7 @@
 import io.seqera.tower.model.DataStudioTemplatesListResponse;
 import io.seqera.tower.model.ListMembersResponse;
 import io.seqera.tower.model.MemberDbDto;
+import io.seqera.tower.model.MountData;
 
 import static io.seqera.tower.cli.utils.ResponseHelper.waitStatus;
 import static io.seqera.tower.model.DataStudioProgressStepStatus.ERRORED;
@@ -184,7 +185,7 @@ protected DataStudioConfiguration studioConfigurationFrom(Long wspId, DataStudio
                 ? studioConfiguration.getLifespanHours()
                 : configOptions.lifespan);
 
-        studioConfiguration.setMountData(getMountDataIds(configOptions, studioConfiguration, wspId));
+        applyMountData(configOptions, studioConfiguration, wspId);
 
         if (configOptions.environment != null) {
             studioConfiguration.setEnvironment(configOptions.environment);
@@ -198,13 +199,19 @@ protected DataStudioConfiguration studioConfigurationFrom(Long wspId, DataStudio
         return studioConfiguration;
     }
 
-    List<String> getMountDataIds(StudioConfigurationOptions studioConfigOptions, DataStudioConfiguration currentStudioConfiguration, Long wspId) throws ApiException {
+    private void applyMountData(StudioConfigurationOptions studioConfigOptions, DataStudioConfiguration studioConfiguration, Long wspId) throws ApiException {
         if (studioConfigOptions.dataLinkRefOptions == null || studioConfigOptions.dataLinkRefOptions.dataLinkRef == null) {
-            return currentStudioConfiguration.getMountData();
+            return;
         }
 
         DataLinkService dataLinkService = new DataLinkService(dataLinksApi(), app());
-        return dataLinkService.getDataLinkIds(studioConfigOptions.dataLinkRefOptions.dataLinkRef, wspId);
+        List<MountData> mountData = dataLinkService.getMountData(studioConfigOptions.dataLinkRefOptions.dataLinkRef, wspId);
+
+        // The platform gives mountDataV2 precedence, so it must be replaced too: a base configuration
+        // fetched from an existing studio carries its current mounts there.
+        studioConfiguration.setMountDataV2(mountData);
+        // Kept for platform versions that predate mountDataV2; they mount the whole data link.
+        studioConfiguration.setMountData(mountData.stream().map(MountData::getDataLinkId).distinct().toList());
     }
 
     protected List<Long> getLabelIds(List<Label> labels, Long wspId) throws ApiException {
diff --git a/src/main/java/io/seqera/tower/cli/commands/studios/DataLinkRefOptions.java b/src/main/java/io/seqera/tower/cli/commands/studios/DataLinkRefOptions.java
index af12b5b0e..376c5a419 100644
--- a/src/main/java/io/seqera/tower/cli/commands/studios/DataLinkRefOptions.java
+++ b/src/main/java/io/seqera/tower/cli/commands/studios/DataLinkRefOptions.java
@@ -29,7 +29,7 @@ public class DataLinkRefOptions {
 
     public static class DataLinkRef {
 
-        @CommandLine.Option(names = {"--mount-data-uris"}, description = "Comma separate list of data-link URIs: s3://nextflow-bucket,s3://another-bucket", split = ",")
+        @CommandLine.Option(names = {"--mount-data-uris"}, description = "Comma separate list of data-link URIs: s3://nextflow-bucket,s3://another-bucket. A URI of a folder inside a data link mounts only that folder: s3://nextflow-bucket/inputs", split = ",")
         private List<String> mountDataUris;
         @CommandLine.Option(names = {"--mount-data"}, description = "Comma separate list of data-link names: nextflow-bucket,my-custom-data-link-name", split = ",")
         private List<String> mountDataNames;
diff --git a/src/main/java/io/seqera/tower/cli/responses/studios/StudiosView.java b/src/main/java/io/seqera/tower/cli/responses/studios/StudiosView.java
index 5a7eca78b..a74ff62f2 100644
--- a/src/main/java/io/seqera/tower/cli/responses/studios/StudiosView.java
+++ b/src/main/java/io/seqera/tower/cli/responses/studios/StudiosView.java
@@ -22,10 +22,15 @@
 import io.seqera.tower.model.DataStudioConfiguration;
 import io.seqera.tower.model.DataStudioDto;
 import io.seqera.tower.model.DataStudioStatusInfo;
+import io.seqera.tower.model.MountData;
 import io.seqera.tower.model.StudioSshDetailsDto;
 import io.seqera.tower.model.UserInfo;
 
 import java.io.PrintWriter;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
 
 import static io.seqera.tower.cli.utils.FormatHelper.formatDescription;
 import static io.seqera.tower.cli.utils.FormatHelper.formatStudioStatus;
@@ -61,8 +66,7 @@ public void toString(PrintWriter out){
         table.addRow("Allowed users", studio.getAllowedUsers() == null || studio.getAllowedUsers().isEmpty() ? "NA" : studio.getAllowedUsers()
                 .stream().map(u -> String.format("%s | %s", u.getUserName(), u.getEmail())).collect(java.util.stream.Collectors.joining(", ")));
         table.addRow("Template", studio.getTemplate() == null ? "NA" : studio.getTemplate().getRepository());
-        table.addRow("Mounted data", studio.getMountedDataLinks() == null ? "NA" : studio.getMountedDataLinks()
-                .stream().map(DataLinkDto::getResourceRef).collect(java.util.stream.Collectors.joining(", ")));
+        table.addRow("Mounted data", formatMountedData(studio.getMountedDataLinks(), config == null ? null : config.getMountDataV2()));
         table.addRow("Compute environment", studio.getComputeEnv() == null ? "NA" : studio.getComputeEnv().getName());
         table.addRow("Region", studio.getComputeEnv() == null ? "NA" : studio.getComputeEnv().getRegion());
         table.addRow("GPU allocated",  config == null ? "-" : String.valueOf(config.getGpu()));
@@ -93,4 +97,22 @@ public void toString(PrintWriter out){
         }
 
     }
+
+    private static String formatMountedData(List<DataLinkDto> mountedDataLinks, List<MountData> mounts) {
+        if (mountedDataLinks == null) {
+            return "NA";
+        }
+        if (mounts == null) {
+            return mountedDataLinks.stream().map(DataLinkDto::getResourceRef).collect(Collectors.joining(", "));
+        }
+        // mountedDataLinks lists each data link once per mount but without the mount path, which only the configuration has.
+        Map<String, String> resourceRefs = new HashMap<>();
+        mountedDataLinks.forEach(dataLink -> resourceRefs.putIfAbsent(dataLink.getId(), dataLink.getResourceRef()));
+        return mounts.stream()
+                .filter(mount -> resourceRefs.containsKey(mount.getDataLinkId()))
+                .map(mount -> mount.getPath() == null || mount.getPath().isEmpty()
+                        ? resourceRefs.get(mount.getDataLinkId())
+                        : resourceRefs.get(mount.getDataLinkId()) + "/" + mount.getPath())
+                .collect(Collectors.joining(", "));
+    }
 }
diff --git a/src/test/java/io/seqera/tower/cli/studios/StudiosCmdTest.java b/src/test/java/io/seqera/tower/cli/studios/StudiosCmdTest.java
index b1e79c0c0..90d393a31 100644
--- a/src/test/java/io/seqera/tower/cli/studios/StudiosCmdTest.java
+++ b/src/test/java/io/seqera/tower/cli/studios/StudiosCmdTest.java
@@ -23,6 +23,7 @@
 import io.seqera.tower.cli.exceptions.StudiosCustomTemplateWithCondaException;
 import io.seqera.tower.cli.exceptions.StudiosTemplateNotFoundException;
 import io.seqera.tower.cli.exceptions.InvalidDataStudioParentCheckpointException;
+import io.seqera.tower.cli.exceptions.DataLinkNotFoundException;
 import io.seqera.tower.cli.exceptions.MultipleDataLinksFoundException;
 import io.seqera.tower.cli.exceptions.TowerRuntimeException;
 import io.seqera.tower.cli.responses.studios.StudiosCreated;
@@ -2951,4 +2952,96 @@ void testStartWithWaitShowsProgressWarnings(MockServerClient mock) {
         assertTrue(out.stdOut.contains("Warning: " + checkpointWarning), out.stdOut);
     }
 
+    private String withMountDataV2(String resource, String mountDataV2) {
+        return new String(loadResource(resource)).replace("\"mountData\": [", "\"mountDataV2\": " + mountDataV2 + ",\n    \"mountData\": [");
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testUpdateWithMountDataUriInsideDataLink(OutputType format, MockServerClient mock) {
+        mockWorkspace(mock);
+        // The studio currently mounts another data link through mountDataV2, which the platform gives precedence.
+        mock.when(
+                request().withMethod("GET").withPath("/studios/3e8370e7").withQueryStringParameter("workspaceId", "75887156211589"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(withMountDataV2("studios/studios_view_response_studio_stopped",
+                        "[{\"dataLinkId\": \"v1-user-1ccf131810375d303bf0402dd8423433\", \"path\": null}]")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        // status check
+        mock.when(
+                request().withMethod("GET").withPath("/data-links")
+                        .withQueryStringParameter("workspaceId", "75887156211589")
+                        .withQueryStringParameter("offset", "0")
+                        .withQueryStringParameter("max", "1"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("data/links/datalinks_list")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        // resource ref searches walking up from the folder to the data link root
+        mock.when(
+                request().withMethod("GET").withPath("/data-links").withQueryStringParameter("workspaceId", "75887156211589"), exactly(3)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("data/links/datalinks_list")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("PUT").withPath("/studios/3e8370e7").withQueryStringParameter("workspaceId", "75887156211589").withBody(json("""
+                           {
+                             "configuration": {
+                               "mountData": ["v1-cloud-c2875f38a7b5c8fe34a5b382b5f9e0c4"],
+                               "mountDataV2": [{"dataLinkId": "v1-cloud-c2875f38a7b5c8fe34a5b382b5f9e0c4", "path": "data/inputs"}]
+                             }
+                           }
+                           """)), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("studios/studios_update_response")).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "studios", "update", "-w", "75887156211589", "-i", "3e8370e7",
+                "--mount-data-uris", "s3://a-test-bucket-eend-us-east-1/data/inputs/");
+
+        assertOutput(format, out, new StudioUpdated("3e8370e7", "3e8370e7", 75887156211589L, "[organization1 / workspace1]"));
+        for (String ref : List.of("s3://a-test-bucket-eend-us-east-1/data/inputs", "s3://a-test-bucket-eend-us-east-1/data", "s3://a-test-bucket-eend-us-east-1")) {
+            mock.verify(request().withMethod("GET").withPath("/data-links").withQueryStringParameter("search", "resourceRef:" + ref), VerificationTimes.once());
+        }
+    }
+
+    @Test
+    void testStartWithMountDataUriNotInAnyDataLink(MockServerClient mock) {
+        mockWorkspace(mock);
+        mock.when(
+                request().withMethod("GET").withPath("/studios/3e8370e7").withQueryStringParameter("workspaceId", "75887156211589"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("studios/studios_view_response_studio_stopped")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("GET").withPath("/data-links").withQueryStringParameter("workspaceId", "75887156211589"), exactly(3)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("data/links/datalinks_list")).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(mock, "studios", "start", "-w", "75887156211589", "-i", "3e8370e7", "--mount-data-uris", "s3://unknown-bucket/data");
+
+        assertEquals(errorMessage(out.app, new DataLinkNotFoundException("resourceRef:s3://unknown-bucket/data", 75887156211589L)), out.stdErr);
+        assertEquals(1, out.exitCode);
+        mock.verify(request().withMethod("PUT").withPath("/studios/3e8370e7/start"), VerificationTimes.never());
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testViewShowsMountPaths(OutputType format, MockServerClient mock) throws JsonProcessingException {
+        mockWorkspace(mock);
+        String studio = withMountDataV2("studios/studios_view_response",
+                "[{\"dataLinkId\": \"v1-user-1ccf131810375d303bf0402dd8423433\", \"path\": \"data/inputs\"}, {\"dataLinkId\": \"v1-user-1ccf131810375d303bf0402dd8423433\", \"path\": null}]");
+        mock.when(
+                request().withMethod("GET").withPath("/studios/3e8370e7").withQueryStringParameter("workspaceId", "75887156211589"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(studio).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "studios", "view", "-w", "75887156211589", "-i", "3e8370e7");
+
+        assertOutput(format, out, new StudiosView(parseJson(studio, DataStudioDto.class), "[organization1 / workspace1]"));
+        if (format == OutputType.console) {
+            assertTrue(out.stdOut.contains("s3://aaa-my-bucket/data/inputs, s3://aaa-my-bucket"), out.stdOut);
+        }
+    }
 }

From bfb369e5bd9fa4abfbe67a35fafb905f29acd9cd Mon Sep 17 00:00:00 2001
From: Cristian Ramon-Cortes <cristian.ramon-cortes@seqera.io>
Date: Mon, 5 Oct 2026 17:46:16 +0200
Subject: [PATCH 2/7] fix(studios): mount data links stored with a trailing
 slash

Data links created before Platform stripped trailing slashes from resource refs (2025-02) can still
be stored as 's3://bucket/'. The mount-data URI lookup strips the slash from the user's URI and
then compared it exactly, so those links could no longer be mounted. Normalise both sides.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../commands/data/links/DataLinkService.java  |  9 +++-
 .../tower/cli/studios/StudiosCmdTest.java     | 44 +++++++++++++++++++
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/src/main/java/io/seqera/tower/cli/commands/data/links/DataLinkService.java b/src/main/java/io/seqera/tower/cli/commands/data/links/DataLinkService.java
index 233e37400..7093bcb49 100644
--- a/src/main/java/io/seqera/tower/cli/commands/data/links/DataLinkService.java
+++ b/src/main/java/io/seqera/tower/cli/commands/data/links/DataLinkService.java
@@ -143,7 +143,7 @@ public List<MountData> getMountData(io.seqera.tower.cli.commands.studios.DataLin
      * so that a folder inside a data link can be mounted (the remainder becomes the mount path).
      */
     private MountData getMountDataByUri(Long wspId, String uri) {
-        String target = uri.endsWith("/") ? uri.substring(0, uri.length() - 1) : uri;
+        String target = stripTrailingSlash(uri);
         int rootEnd = target.indexOf("://") + 2;
         String candidate = target;
         while (true) {
@@ -160,6 +160,10 @@ private MountData getMountDataByUri(Long wspId, String uri) {
         }
     }
 
+    private static String stripTrailingSlash(String ref) {
+        return ref != null && ref.endsWith("/") ? ref.substring(0, ref.length() - 1) : ref;
+    }
+
     private DataLinkDto getDataLinkByName(Long wspId, String credId, String name) {
         return getDataLinkBySearchAndFindExactMatch(wspId, name, credId, datalink -> name.equals(datalink.getName()));
     }
@@ -169,7 +173,8 @@ private DataLinkDto getDataLinkByResourceRef(Long wspId, String credId, String r
     }
 
     private Optional<DataLinkDto> findDataLinkByResourceRef(Long wspId, String resourceRef) {
-        return findDataLinkBySearchAndExactMatch(wspId, getResourceRefKeywordParam(resourceRef), null, datalink -> resourceRef.equals(datalink.getResourceRef()));
+        // Data links created before Platform normalised resource refs may still be stored with a trailing slash
+        return findDataLinkBySearchAndExactMatch(wspId, getResourceRefKeywordParam(resourceRef), null, datalink -> resourceRef.equals(stripTrailingSlash(datalink.getResourceRef())));
     }
 
     private DataLinkDto getDataLinkBySearchAndFindExactMatch(Long wspId, String search, String credId, Predicate<DataLinkDto> filter) {
diff --git a/src/test/java/io/seqera/tower/cli/studios/StudiosCmdTest.java b/src/test/java/io/seqera/tower/cli/studios/StudiosCmdTest.java
index 90d393a31..0904fac17 100644
--- a/src/test/java/io/seqera/tower/cli/studios/StudiosCmdTest.java
+++ b/src/test/java/io/seqera/tower/cli/studios/StudiosCmdTest.java
@@ -3025,6 +3025,50 @@ void testStartWithMountDataUriNotInAnyDataLink(MockServerClient mock) {
         mock.verify(request().withMethod("PUT").withPath("/studios/3e8370e7/start"), VerificationTimes.never());
     }
 
+    @Test
+    void testUpdateWithMountDataUriMatchesDataLinkStoredWithTrailingSlash(MockServerClient mock) {
+        mockWorkspace(mock);
+        mock.when(
+                request().withMethod("GET").withPath("/studios/3e8370e7").withQueryStringParameter("workspaceId", "75887156211589"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("studios/studios_view_response_studio_stopped")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("GET").withPath("/data-links")
+                        .withQueryStringParameter("workspaceId", "75887156211589")
+                        .withQueryStringParameter("offset", "0")
+                        .withQueryStringParameter("max", "1"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("data/links/datalinks_list")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        // Data links created before Platform stripped trailing slashes keep them in their resource ref
+        String legacyDataLinks = new String(loadResource("data/links/datalinks_list"))
+                .replace("\"resourceRef\": \"s3://a-test-bucket-eend-us-east-1\"", "\"resourceRef\": \"s3://a-test-bucket-eend-us-east-1/\"");
+        mock.when(
+                request().withMethod("GET").withPath("/data-links").withQueryStringParameter("workspaceId", "75887156211589"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(legacyDataLinks).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("PUT").withPath("/studios/3e8370e7").withQueryStringParameter("workspaceId", "75887156211589").withBody(json("""
+                           {
+                             "configuration": {
+                               "mountData": ["v1-cloud-c2875f38a7b5c8fe34a5b382b5f9e0c4"],
+                               "mountDataV2": [{"dataLinkId": "v1-cloud-c2875f38a7b5c8fe34a5b382b5f9e0c4"}]
+                             }
+                           }
+                           """)), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("studios/studios_update_response")).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(mock, "studios", "update", "-w", "75887156211589", "-i", "3e8370e7",
+                "--mount-data-uris", "s3://a-test-bucket-eend-us-east-1/");
+
+        assertEquals("", out.stdErr);
+        assertEquals(0, out.exitCode);
+    }
+
     @ParameterizedTest
     @EnumSource(OutputType.class)
     void testViewShowsMountPaths(OutputType format, MockServerClient mock) throws JsonProcessingException {

From d951d2691010fd9ef30873261b6fad533f71620e Mon Sep 17 00:00:00 2001
From: Cristian Ramon-Cortes <cristian.ramon-cortes@seqera.io>
Date: Mon, 5 Oct 2026 17:46:16 +0200
Subject: [PATCH 3/7] feat(datasets): link datasets from a URL

API 1.145.0 added linked datasets: a dataset created with
sourceType=LINKED whose versions point to a public HTTP(S) CSV/TSV URL
(POST /datasets/{id}/link) instead of an uploaded file. tw could only
upload files, so:

- 'tw datasets add --url <url>' validates the URL first
  (POST /datasets/validate-url, as the UI does, so a bad URL does not
  leave an empty dataset behind), creates a LINKED dataset and links
  the URL as its first version.
- 'tw datasets update --url <url>' links a new version.
- 'datasets view ... versions' shows the source URL of linked versions,
  which have no file name (the table would otherwise hit a null cell).

preview-url and the version preview back UI widgets and add no CLI
capability.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../tower/cli/commands/datasets/AddCmd.java   |  46 ++++--
 .../cli/commands/datasets/UpdateCmd.java      |  14 +-
 .../datasets/DatasetVersionsList.java         |  10 +-
 .../tower/cli/datasets/DatasetsCmdTest.java   | 133 ++++++++++++++++++
 4 files changed, 191 insertions(+), 12 deletions(-)

diff --git a/src/main/java/io/seqera/tower/cli/commands/datasets/AddCmd.java b/src/main/java/io/seqera/tower/cli/commands/datasets/AddCmd.java
index fa1729801..41a976c8c 100644
--- a/src/main/java/io/seqera/tower/cli/commands/datasets/AddCmd.java
+++ b/src/main/java/io/seqera/tower/cli/commands/datasets/AddCmd.java
@@ -24,6 +24,10 @@
 import io.seqera.tower.cli.responses.datasets.DatasetCreate;
 import io.seqera.tower.model.CreateDatasetRequest;
 import io.seqera.tower.model.CreateDatasetResponse;
+import io.seqera.tower.model.LinkVersionRequest;
+import io.seqera.tower.model.SourceType;
+import io.seqera.tower.model.ValidateUrlRequest;
+import io.seqera.tower.model.ValidateUrlResponse;
 import picocli.CommandLine;
 
 import java.io.File;
@@ -45,9 +49,12 @@ public class AddCmd extends AbstractDatasetsCmd {
     @CommandLine.Option(names = {"--header"}, description = "Treat first row as header. Default: false.")
     public boolean header = false;
 
-    @CommandLine.Parameters(index = "0", paramLabel = "FILENAME", description = "Data file to upload", arity = "1")
+    @CommandLine.Parameters(index = "0", paramLabel = "FILENAME", description = "Data file to upload. Not allowed with --url.", arity = "0..1")
     Path fileName = null;
 
+    @CommandLine.Option(names = {"--url"}, description = "Public HTTP or HTTPS URL of a CSV or TSV file to link instead of uploading a file. Runs read the file from the URL.")
+    public String url;
+
     @CommandLine.Mixin
     public WorkspaceRequiredOptions workspace;
 
@@ -56,27 +63,48 @@ public class AddCmd extends AbstractDatasetsCmd {
 
     @Override
     protected Response exec() throws ApiException, IOException {
-        File dataset = fileName.toFile();
-        if (!dataset.exists()) {
-            throw new TowerException(String.format("File path '%s' do not exists.", fileName));
+        if ((fileName == null) == (url == null)) {
+            throw new TowerException("Provide either a FILENAME to upload or a --url to link");
         }
-
-        if (dataset.isDirectory()) {
-            throw new TowerException(String.format("File path '%s' must be a file, not a directory.", fileName));
+        if (fileName != null) {
+            File dataset = fileName.toFile();
+            if (!dataset.exists()) {
+                throw new TowerException(String.format("File path '%s' do not exists.", fileName));
+            }
+
+            if (dataset.isDirectory()) {
+                throw new TowerException(String.format("File path '%s' must be a file, not a directory.", fileName));
+            }
         }
 
         Long wspId = workspaceId(workspace.workspace);
+        // Like the UI, check the URL before creating the dataset so that an unusable URL leaves no empty dataset behind.
+        if (url != null) {
+            ValidateUrlResponse validation = datasetsApi().validateDatasetUrl(new ValidateUrlRequest().url(url), wspId);
+            if (!Boolean.TRUE.equals(validation.getValid())) {
+                throw new TowerException(String.format("Dataset URL '%s' cannot be linked: %s", url, validation.getErrorMessage()));
+            }
+        }
+
         CreateDatasetRequest request = new CreateDatasetRequest();
         request.setName(name);
         request.setDescription(description);
+        if (url != null) {
+            request.setSourceType(SourceType.LINKED);
+        }
 
         if (overwrite) tryDeleteDataset(name, wspId);
 
         CreateDatasetResponse response = datasetsApi().createDatasetV2(request, wspId);
+        String datasetId = response.getDataset().getId();
 
-        datasetsApi().uploadDatasetV2(response.getDataset().getId(), wspId, header, fileName.toFile());
+        if (url != null) {
+            datasetsApi().linkDatasetVersion(datasetId, new LinkVersionRequest().url(url).hasHeader(header), wspId);
+        } else {
+            datasetsApi().uploadDatasetV2(datasetId, wspId, header, fileName.toFile());
+        }
 
-        return new DatasetCreate(response.getDataset().getName(), workspace.workspace, response.getDataset().getId());
+        return new DatasetCreate(response.getDataset().getName(), workspace.workspace, datasetId);
     }
 
     private void tryDeleteDataset(String datasetName, Long wspId) throws ApiException {
diff --git a/src/main/java/io/seqera/tower/cli/commands/datasets/UpdateCmd.java b/src/main/java/io/seqera/tower/cli/commands/datasets/UpdateCmd.java
index 60a3bef84..03bedeabb 100644
--- a/src/main/java/io/seqera/tower/cli/commands/datasets/UpdateCmd.java
+++ b/src/main/java/io/seqera/tower/cli/commands/datasets/UpdateCmd.java
@@ -22,6 +22,7 @@
 import io.seqera.tower.cli.responses.Response;
 import io.seqera.tower.cli.responses.datasets.DatasetUpdate;
 import io.seqera.tower.model.DatasetDto;
+import io.seqera.tower.model.LinkVersionRequest;
 import io.seqera.tower.model.UpdateDatasetRequest;
 import picocli.CommandLine;
 
@@ -46,15 +47,21 @@ public class UpdateCmd extends AbstractDatasetsCmd {
     @CommandLine.Option(names = {"--header"}, description = "Treat first row as header")
     public boolean header = false;
 
-    @CommandLine.Option(names = {"-f", "--file"}, description = "Data file to upload")
+    @CommandLine.Option(names = {"-f", "--file"}, description = "Data file to upload as a new version")
     Path fileName = null;
 
+    @CommandLine.Option(names = {"--url"}, description = "Public HTTP or HTTPS URL of a CSV or TSV file to link as a new version. Only for datasets created with --url.")
+    public String url;
+
     @CommandLine.Mixin
     public WorkspaceRequiredOptions workspace;
 
     @Override
     protected Response exec() throws ApiException, IOException {
-        if (fileName == null && header) {
+        if (fileName != null && url != null) {
+            throw new TowerException("Provide either a --file to upload or a --url to link, not both");
+        }
+        if (fileName == null && url == null && header) {
             throw new TowerException("Please provide a new file version to upload or remove the --header option");
         }
 
@@ -69,6 +76,9 @@ protected Response exec() throws ApiException, IOException {
         if (fileName != null) {
             datasetsApi().uploadDatasetV2(dataset.getId(), wspId, header, fileName.toFile());
         }
+        if (url != null) {
+            datasetsApi().linkDatasetVersion(dataset.getId(), new LinkVersionRequest().url(url).hasHeader(header), wspId);
+        }
 
         return new DatasetUpdate(dataset.getName(), workspace.workspace, dataset.getId());
     }
diff --git a/src/main/java/io/seqera/tower/cli/responses/datasets/DatasetVersionsList.java b/src/main/java/io/seqera/tower/cli/responses/datasets/DatasetVersionsList.java
index b978669a4..2d8b889bc 100644
--- a/src/main/java/io/seqera/tower/cli/responses/datasets/DatasetVersionsList.java
+++ b/src/main/java/io/seqera/tower/cli/responses/datasets/DatasetVersionsList.java
@@ -46,9 +46,17 @@ public void toString(PrintWriter out) {
 
         TableList table = new TableList(out, 6, "Version", "Has Header", "Media Type", "File Name", "URL", "Disabled").sortBy(0);
         table.setPrefix("    ");
-        versions.forEach(v -> table.addRow(v.getVersion().toString(), v.getHasHeader().toString(), v.getMediaType(), v.getFileName(), v.getUrl(), String.valueOf(Boolean.TRUE.equals(v.getDisabled()))));
+        versions.forEach(v -> table.addRow(v.getVersion().toString(), v.getHasHeader().toString(), v.getMediaType(), fileNameOrSourceUrl(v), v.getUrl(), String.valueOf(Boolean.TRUE.equals(v.getDisabled()))));
         table.print();
 
         out.println("");
     }
+
+    // Linked versions have no uploaded file, they point to a source URL instead.
+    private static String fileNameOrSourceUrl(DatasetVersionDto version) {
+        if (version.getFileName() != null) {
+            return version.getFileName();
+        }
+        return version.getLinkedSource() == null || version.getLinkedSource().getUrl() == null ? "" : version.getLinkedSource().getUrl();
+    }
 }
diff --git a/src/test/java/io/seqera/tower/cli/datasets/DatasetsCmdTest.java b/src/test/java/io/seqera/tower/cli/datasets/DatasetsCmdTest.java
index 17ba47fdd..0f171a8a4 100644
--- a/src/test/java/io/seqera/tower/cli/datasets/DatasetsCmdTest.java
+++ b/src/test/java/io/seqera/tower/cli/datasets/DatasetsCmdTest.java
@@ -37,7 +37,10 @@
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.EnumSource;
 import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
 import org.mockserver.client.MockServerClient;
+import org.mockserver.matchers.MatchType;
+import org.mockserver.verify.VerificationTimes;
 import org.mockserver.model.JsonBody;
 import org.mockserver.model.MediaType;
 
@@ -640,4 +643,134 @@ void testVersionsShowsDisabled(OutputType format, MockServerClient mock) throws
             assertTrue(out.stdOut.contains("Disabled"), out.stdOut);
         }
     }
+
+    private static final String LINK_URL = "https://example.com/samples.csv";
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testAddWithUrl(OutputType format, MockServerClient mock) {
+        mock.when(
+                request().withMethod("POST").withPath("/datasets/validate-url")
+                        .withQueryStringParameter("workspaceId", "249664655368293")
+                        .withBody(json("{\"url\": \"" + LINK_URL + "\"}", MatchType.STRICT)), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody("{\"valid\": true, \"mediaType\": \"text/csv\"}").withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("POST").withPath("/datasets")
+                        .withQueryStringParameter("workspaceId", "249664655368293")
+                        .withBody(json("{\"name\": \"dataset3\", \"description\": \"Dataset 3 description.\", \"sourceType\": \"LINKED\"}", MatchType.STRICT)), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("datasets/dataset_created_response")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("POST").withPath("/datasets/1W3BTHWgRH71OJmOPMdG7S/link")
+                        .withQueryStringParameter("workspaceId", "249664655368293")
+                        .withBody(json("{\"url\": \"" + LINK_URL + "\", \"hasHeader\": true}", MatchType.STRICT)), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody("{\"version\": {\"datasetId\": \"1W3BTHWgRH71OJmOPMdG7S\", \"version\": 1}}").withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "datasets", "add", "-w", "249664655368293", "-n", "dataset3", "-d", "Dataset 3 description.", "--url", LINK_URL, "--header");
+
+        assertOutput(format, out, new DatasetCreate("dataset3", "249664655368293", "1W3BTHWgRH71OJmOPMdG7S"));
+        mock.verify(request().withPath("/datasets/1W3BTHWgRH71OJmOPMdG7S/upload"), VerificationTimes.never());
+    }
+
+    @Test
+    void testAddWithInvalidUrlCreatesNothing(MockServerClient mock) {
+        mock.when(
+                request().withMethod("POST").withPath("/datasets/validate-url"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody("{\"valid\": false, \"errorCode\": \"UNSUPPORTED_FORMAT\", \"errorMessage\": \"The URL does not return a CSV or TSV file.\"}").withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(mock, "datasets", "add", "-w", "249664655368293", "-n", "dataset3", "--url", LINK_URL);
+
+        assertEquals(errorMessage(out.app, new TowerException("Dataset URL '" + LINK_URL + "' cannot be linked: The URL does not return a CSV or TSV file.")), out.stdErr);
+        assertEquals(1, out.exitCode);
+        mock.verify(request().withMethod("POST").withPath("/datasets"), VerificationTimes.never());
+    }
+
+    @Test
+    void testAddRequiresEitherFileOrUrl(MockServerClient mock) throws IOException {
+
+        ExecOut neither = exec(mock, "datasets", "add", "-w", "249664655368293", "-n", "dataset3");
+        assertEquals(1, neither.exitCode);
+        assertEquals(errorMessage(neither.app, new TowerException("Provide either a FILENAME to upload or a --url to link")), neither.stdErr);
+
+        ExecOut both = exec(mock, "datasets", "add", "-w", "249664655368293", "-n", "dataset3", "--url", LINK_URL,
+                tempFile(new String(loadResource("datasets/dataset_data", "csv"), StandardCharsets.UTF_8), "data", ".csv"));
+        assertEquals(1, both.exitCode);
+        assertEquals(errorMessage(both.app, new TowerException("Provide either a FILENAME to upload or a --url to link")), both.stdErr);
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testUpdateWithUrl(OutputType format, MockServerClient mock) {
+        mock.when(
+                request().withMethod("GET").withPath("/datasets/4D9TP0w2pM0qmwqVHgrgBK/metadata")
+                        .withQueryStringParameter("workspaceId", "249664655368293"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("datasets/dataset_metadata")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("PUT").withPath("/datasets/4D9TP0w2pM0qmwqVHgrgBK")
+                        .withQueryStringParameter("workspaceId", "249664655368293"), exactly(1)
+        ).respond(
+                response().withStatusCode(204)
+        );
+        mock.when(
+                request().withMethod("POST").withPath("/datasets/4D9TP0w2pM0qmwqVHgrgBK/link")
+                        .withQueryStringParameter("workspaceId", "249664655368293")
+                        .withBody(json("{\"url\": \"" + LINK_URL + "\", \"hasHeader\": false}", MatchType.STRICT)), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody("{\"version\": {\"datasetId\": \"4D9TP0w2pM0qmwqVHgrgBK\", \"version\": 3}}").withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "datasets", "update", "-w", "249664655368293", "-i", "4D9TP0w2pM0qmwqVHgrgBK", "--url", LINK_URL);
+
+        assertOutput(format, out, new DatasetUpdate("dataset1", "249664655368293", "4D9TP0w2pM0qmwqVHgrgBK"));
+    }
+
+    @Test
+    void testUpdateRejectsFileAndUrl(MockServerClient mock) throws IOException {
+        ExecOut out = exec(mock, "datasets", "update", "-w", "249664655368293", "-i", "4D9TP0w2pM0qmwqVHgrgBK", "--url", LINK_URL,
+                "-f", tempFile(new String(loadResource("datasets/dataset_data", "csv"), StandardCharsets.UTF_8), "data", ".csv"));
+
+        assertEquals(errorMessage(out.app, new TowerException("Provide either a --file to upload or a --url to link, not both")), out.stdErr);
+        assertEquals(1, out.exitCode);
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testVersionsShowsLinkedAndDisabled(OutputType format, MockServerClient mock) throws JsonProcessingException {
+        String versions = """
+                {"versions": [
+                  {"datasetId": "4D9TP0w2pM0qmwqVHgrgBK", "version": 1, "hasHeader": true, "mediaType": "text/csv", "disabled": true,
+                   "url": "https://api/workspaces/249664655368293/datasets/4D9TP0w2pM0qmwqVHgrgBK/v/1/n/samples.csv",
+                   "linkedSource": {"url": "https://example.com/samples.csv"}}
+                ]}
+                """;
+        mock.when(
+                request().withMethod("GET").withPath("/datasets/4D9TP0w2pM0qmwqVHgrgBK/metadata")
+                        .withQueryStringParameter("workspaceId", "249664655368293"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(loadResource("datasets/dataset_metadata")).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("GET").withPath("/datasets/4D9TP0w2pM0qmwqVHgrgBK/versions")
+                        .withQueryStringParameter("workspaceId", "249664655368293"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(versions).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "datasets", "view", "-w", "249664655368293", "-i", "4D9TP0w2pM0qmwqVHgrgBK", "versions");
+
+        assertOutput(format, out, new DatasetVersionsList(parseJson(versions, ListDatasetVersionsResponse.class).getVersions(), "4D9TP0w2pM0qmwqVHgrgBK", "249664655368293"));
+        if (format == OutputType.console) {
+            assertTrue(out.stdOut.contains("https://example.com/samples.csv"), out.stdOut);
+            assertTrue(out.stdOut.contains("Disabled"), out.stdOut);
+        }
+    }
 }

From fd1c47994bef892a15347368ec4b2650f84baad8 Mon Sep 17 00:00:00 2001
From: Cristian Ramon-Cortes <cristian.ramon-cortes@seqera.io>
Date: Mon, 5 Oct 2026 17:46:16 +0200
Subject: [PATCH 4/7] feat(members): add roles command

listUserRolesInOrganization (API 1.145, /orgs/{orgId}/users/{userId}/roles)
had no tw command.

Add 'tw members roles' to show a member's role in each workspace and
whether it was granted directly or through a team.

deleteWorkspaceUser is not added: it removes the same participant as
'tw participants delete' (both call MemberDeleteService.deleteParticipant
in the backend), only looked up by user ID instead of participant ID.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../seqera/tower/cli/commands/MembersCmd.java |  2 +
 .../tower/cli/commands/members/RolesCmd.java  | 44 +++++++++++++
 .../responses/members/MemberRolesList.java    | 63 +++++++++++++++++++
 .../tower/cli/members/MembersCmdTest.java     | 28 +++++++++
 4 files changed, 137 insertions(+)
 create mode 100644 src/main/java/io/seqera/tower/cli/commands/members/RolesCmd.java
 create mode 100644 src/main/java/io/seqera/tower/cli/responses/members/MemberRolesList.java

diff --git a/src/main/java/io/seqera/tower/cli/commands/MembersCmd.java b/src/main/java/io/seqera/tower/cli/commands/MembersCmd.java
index 2efc77e7d..d204c239b 100644
--- a/src/main/java/io/seqera/tower/cli/commands/MembersCmd.java
+++ b/src/main/java/io/seqera/tower/cli/commands/MembersCmd.java
@@ -20,6 +20,7 @@
 import io.seqera.tower.cli.commands.members.DeleteCmd;
 import io.seqera.tower.cli.commands.members.LeaveCmd;
 import io.seqera.tower.cli.commands.members.ListCmd;
+import io.seqera.tower.cli.commands.members.RolesCmd;
 import io.seqera.tower.cli.commands.members.UpdateCmd;
 import picocli.CommandLine;
 
@@ -32,6 +33,7 @@
                 DeleteCmd.class,
                 UpdateCmd.class,
                 LeaveCmd.class,
+                RolesCmd.class,
         }
 )
 public class MembersCmd extends AbstractRootCmd {
diff --git a/src/main/java/io/seqera/tower/cli/commands/members/RolesCmd.java b/src/main/java/io/seqera/tower/cli/commands/members/RolesCmd.java
new file mode 100644
index 000000000..60f0e97f8
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/commands/members/RolesCmd.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.commands.members;
+
+import io.seqera.tower.ApiException;
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.responses.members.MemberRolesList;
+import io.seqera.tower.model.MemberDbDto;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+@Command(
+        name = "roles",
+        description = "List the workspace roles of an organization member, granted directly or through teams"
+)
+public class RolesCmd extends AbstractMembersClass {
+
+    @Option(names = {"-u", "--user"}, description = "Username or email address of the organization member.", required = true)
+    public String user;
+
+    @Option(names = {"-o", "--organization"}, description = "Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'.", required = true)
+    public String organizationRef;
+
+    @Override
+    protected Response exec() throws ApiException {
+        Long orgId = findOrganizationByRef(organizationRef).getOrgId();
+        MemberDbDto member = findMemberByUser(orgId, user);
+        return new MemberRolesList(organizationRef, orgsApi().listUserRolesInOrganization(orgId, member.getUserId()));
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/responses/members/MemberRolesList.java b/src/main/java/io/seqera/tower/cli/responses/members/MemberRolesList.java
new file mode 100644
index 000000000..b58487f5e
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/responses/members/MemberRolesList.java
@@ -0,0 +1,63 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.responses.members;
+
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.utils.TableList;
+import io.seqera.tower.model.ListUserRolesResponse;
+import io.seqera.tower.model.UserWorkspaceRoleDto;
+import io.seqera.tower.model.WspRoleSourceType;
+
+import java.io.PrintWriter;
+
+public class MemberRolesList extends Response {
+
+    public final String organizationName;
+    public final ListUserRolesResponse userRoles;
+
+    public MemberRolesList(String organizationName, ListUserRolesResponse userRoles) {
+        this.organizationName = organizationName;
+        this.userRoles = userRoles;
+    }
+
+    @Override
+    public Object getJSON() {
+        return userRoles;
+    }
+
+    @Override
+    public void toString(PrintWriter out) {
+        out.println(ansi(String.format("%n  @|bold Workspace roles of '%s' in %s organization:|@%n", userRoles.getUser().getUserName(), organizationName)));
+
+        if (userRoles.getUserWorkspaces() == null || userRoles.getUserWorkspaces().isEmpty()) {
+            out.println(ansi("    @|yellow No workspace roles found|@"));
+            return;
+        }
+
+        TableList table = new TableList(out, 4, "Workspace ID", "Workspace Name", "Role", "Granted via");
+        table.setPrefix("    ");
+        userRoles.getUserWorkspaces().forEach(ws -> ws.getRoles().forEach(role ->
+                table.addRow(ws.getWorkspaceId().toString(), ws.getWorkspaceName(), role.getRole(), grantedVia(role))
+        ));
+        table.print();
+        out.println("");
+    }
+
+    private static String grantedVia(UserWorkspaceRoleDto role) {
+        return role.getRoleSourceType() == WspRoleSourceType.team ? "team " + role.getSourceTeamName() : "direct";
+    }
+}
diff --git a/src/test/java/io/seqera/tower/cli/members/MembersCmdTest.java b/src/test/java/io/seqera/tower/cli/members/MembersCmdTest.java
index c4fa35187..906c5b20a 100644
--- a/src/test/java/io/seqera/tower/cli/members/MembersCmdTest.java
+++ b/src/test/java/io/seqera/tower/cli/members/MembersCmdTest.java
@@ -16,6 +16,8 @@
 
 package io.seqera.tower.cli.members;
 
+import io.seqera.tower.model.ListUserRolesResponse;
+import io.seqera.tower.cli.responses.members.MemberRolesList;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import io.seqera.tower.cli.BaseCmdTest;
 import io.seqera.tower.cli.commands.enums.OutputType;
@@ -332,4 +334,30 @@ void testLeave(OutputType format, MockServerClient mock) {
         ExecOut out = exec(format, mock, "members", "leave", "-o", "organization1");
         assertOutput(format, out, new MembersLeave("organization1"));
     }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testRoles(OutputType format, MockServerClient mock) throws JsonProcessingException {
+        mock.when(request().withMethod("GET").withPath("/user-info"))
+                .respond(response().withStatusCode(200).withBody(loadResource("user")).withContentType(MediaType.APPLICATION_JSON));
+        mock.when(request().withMethod("GET").withPath("/user/1264/workspaces"))
+                .respond(response().withStatusCode(200).withBody(loadResource("workspaces/workspaces_list")).withContentType(MediaType.APPLICATION_JSON));
+        mock.when(request().withMethod("GET").withPath("/orgs/27736513644467/members").withQueryStringParameter("search", "julio"), exactly(1))
+                .respond(response().withStatusCode(200).withBody("""
+                        {"members": [{"memberId": 255080245994226, "userId": 4242, "userName": "julio", "email": "julio@seqera.io", "role": "member"}], "totalSize": 1}
+                        """).withContentType(MediaType.APPLICATION_JSON));
+        String body = """
+                {"user": {"memberId": 255080245994226, "userId": 4242, "userName": "julio", "email": "julio@seqera.io", "role": "member"},
+                 "userWorkspaces": [{"workspaceId": 75887156211589, "workspaceName": "workspace1", "participantId": 9,
+                   "roles": [{"role": "launch", "roleSourceType": "individual"},
+                             {"role": "maintain", "roleSourceType": "team", "sourceTeamId": 7, "sourceTeamName": "eng", "sourceTeamType": "regular"}],
+                   "permissions": [{"permission": "pipeline:launch", "roles": ["launch", "maintain"]}]}]}
+                """;
+        mock.when(request().withMethod("GET").withPath("/orgs/27736513644467/users/4242/roles"), exactly(1))
+                .respond(response().withStatusCode(200).withBody(body).withContentType(MediaType.APPLICATION_JSON));
+
+        ExecOut out = exec(format, mock, "members", "roles", "-o", "organization1", "-u", "julio");
+
+        assertOutput(format, out, new MemberRolesList("organization1", parseJson(body, ListUserRolesResponse.class)));
+    }
 }

From 1e95133a54ada51d4aeec8f5816d385747c99cf8 Mon Sep 17 00:00:00 2001
From: Cristian Ramon-Cortes <cristian.ramon-cortes@seqera.io>
Date: Mon, 5 Oct 2026 17:46:16 +0200
Subject: [PATCH 5/7] feat(roles): add custom role commands

Platform API 1.145 added custom workspace roles (/roles), but tw could
only assign them by name through 'participants update --role'; there
was no way to see which roles exist or to create them.

Add 'tw roles' with list, view, add, update, delete and permissions.
The update endpoint replaces name, description and permissions as a
whole, so 'roles update' reads the current role and only overrides the
fields that were passed.

The /roles/permissions name filter is typed as int64 in the API spec,
so 'roles permissions' does not expose it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/main/java/io/seqera/tower/cli/Tower.java  |   2 +
 .../tower/cli/commands/AbstractApiCmd.java    |   6 +
 .../seqera/tower/cli/commands/RolesCmd.java   |  40 ++++
 .../tower/cli/commands/roles/AddCmd.java      |  60 ++++++
 .../tower/cli/commands/roles/DeleteCmd.java   |  44 ++++
 .../tower/cli/commands/roles/ListCmd.java     |  59 ++++++
 .../cli/commands/roles/PermissionsCmd.java    |  41 ++++
 .../tower/cli/commands/roles/UpdateCmd.java   |  66 ++++++
 .../tower/cli/commands/roles/ViewCmd.java     |  43 ++++
 .../tower/cli/responses/roles/RoleAdded.java  |  35 ++++
 .../cli/responses/roles/RoleDeleted.java      |  35 ++++
 .../responses/roles/RolePermissionsList.java  |  49 +++++
 .../cli/responses/roles/RoleUpdated.java      |  35 ++++
 .../tower/cli/responses/roles/RoleView.java   |  53 +++++
 .../tower/cli/responses/roles/RolesList.java  |  66 ++++++
 .../seqera/tower/cli/roles/RolesCmdTest.java  | 190 ++++++++++++++++++
 16 files changed, 824 insertions(+)
 create mode 100644 src/main/java/io/seqera/tower/cli/commands/RolesCmd.java
 create mode 100644 src/main/java/io/seqera/tower/cli/commands/roles/AddCmd.java
 create mode 100644 src/main/java/io/seqera/tower/cli/commands/roles/DeleteCmd.java
 create mode 100644 src/main/java/io/seqera/tower/cli/commands/roles/ListCmd.java
 create mode 100644 src/main/java/io/seqera/tower/cli/commands/roles/PermissionsCmd.java
 create mode 100644 src/main/java/io/seqera/tower/cli/commands/roles/UpdateCmd.java
 create mode 100644 src/main/java/io/seqera/tower/cli/commands/roles/ViewCmd.java
 create mode 100644 src/main/java/io/seqera/tower/cli/responses/roles/RoleAdded.java
 create mode 100644 src/main/java/io/seqera/tower/cli/responses/roles/RoleDeleted.java
 create mode 100644 src/main/java/io/seqera/tower/cli/responses/roles/RolePermissionsList.java
 create mode 100644 src/main/java/io/seqera/tower/cli/responses/roles/RoleUpdated.java
 create mode 100644 src/main/java/io/seqera/tower/cli/responses/roles/RoleView.java
 create mode 100644 src/main/java/io/seqera/tower/cli/responses/roles/RolesList.java
 create mode 100644 src/test/java/io/seqera/tower/cli/roles/RolesCmdTest.java

diff --git a/src/main/java/io/seqera/tower/cli/Tower.java b/src/main/java/io/seqera/tower/cli/Tower.java
index fb37fca48..68c8c9e70 100644
--- a/src/main/java/io/seqera/tower/cli/Tower.java
+++ b/src/main/java/io/seqera/tower/cli/Tower.java
@@ -37,6 +37,7 @@
 import io.seqera.tower.cli.commands.ParticipantsCmd;
 import io.seqera.tower.cli.commands.PipelinesCmd;
 import io.seqera.tower.cli.commands.PipelineSchemasCmd;
+import io.seqera.tower.cli.commands.RolesCmd;
 import io.seqera.tower.cli.commands.RunsCmd;
 import io.seqera.tower.cli.commands.SecretsCmd;
 import io.seqera.tower.cli.commands.SshKeysCmd;
@@ -77,6 +78,7 @@
                 ParticipantsCmd.class,
                 PipelinesCmd.class,
                 PipelineSchemasCmd.class,
+                RolesCmd.class,
                 RunsCmd.class,
                 SshKeysCmd.class,
                 TeamsCmd.class,
diff --git a/src/main/java/io/seqera/tower/cli/commands/AbstractApiCmd.java b/src/main/java/io/seqera/tower/cli/commands/AbstractApiCmd.java
index 842b619b9..5f1221e41 100644
--- a/src/main/java/io/seqera/tower/cli/commands/AbstractApiCmd.java
+++ b/src/main/java/io/seqera/tower/cli/commands/AbstractApiCmd.java
@@ -36,6 +36,7 @@
 import io.seqera.tower.api.PipelineVersionsApi;
 import io.seqera.tower.api.PipelinesApi;
 import io.seqera.tower.api.PlatformsApi;
+import io.seqera.tower.api.RolesApi;
 import io.seqera.tower.api.ServiceInfoApi;
 import io.seqera.tower.api.SshKeysApi;
 import io.seqera.tower.api.StudiosApi;
@@ -136,6 +137,7 @@ public abstract class AbstractApiCmd extends AbstractCmd {
     private PipelineSecretsApi pipelineSecretsApi;
     private PipelineVersionsApi pipelineVersionsApi;
     private PlatformsApi platformsApi;
+    private RolesApi rolesApi;
     private ServiceInfoApi serviceInfoApi;
     private SshKeysApi sshKeysApi;
     private StudiosApi studiosApi;
@@ -267,6 +269,10 @@ protected PlatformsApi platformsApi() throws ApiException {
         return platformsApi == null ? new PlatformsApi(apiClient()) : platformsApi;
     }
 
+    protected RolesApi rolesApi() throws ApiException {
+        return rolesApi == null ? new RolesApi(apiClient()) : rolesApi;
+    }
+
     protected ServiceInfoApi serviceInfoApi() throws ApiException {
         return serviceInfoApi == null ? new ServiceInfoApi(apiClient()) : serviceInfoApi;
     }
diff --git a/src/main/java/io/seqera/tower/cli/commands/RolesCmd.java b/src/main/java/io/seqera/tower/cli/commands/RolesCmd.java
new file mode 100644
index 000000000..74db22e56
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/commands/RolesCmd.java
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.commands;
+
+import io.seqera.tower.cli.commands.roles.AddCmd;
+import io.seqera.tower.cli.commands.roles.DeleteCmd;
+import io.seqera.tower.cli.commands.roles.ListCmd;
+import io.seqera.tower.cli.commands.roles.PermissionsCmd;
+import io.seqera.tower.cli.commands.roles.UpdateCmd;
+import io.seqera.tower.cli.commands.roles.ViewCmd;
+import picocli.CommandLine.Command;
+
+@Command(
+        name = "roles",
+        description = "Manage workspace roles. Custom roles are not available for Seqera Cloud Basic organizations.",
+        subcommands = {
+                ListCmd.class,
+                ViewCmd.class,
+                AddCmd.class,
+                UpdateCmd.class,
+                DeleteCmd.class,
+                PermissionsCmd.class,
+        }
+)
+public class RolesCmd extends AbstractRootCmd {
+}
diff --git a/src/main/java/io/seqera/tower/cli/commands/roles/AddCmd.java b/src/main/java/io/seqera/tower/cli/commands/roles/AddCmd.java
new file mode 100644
index 000000000..cf211d057
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/commands/roles/AddCmd.java
@@ -0,0 +1,60 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.commands.roles;
+
+import io.seqera.tower.ApiException;
+import io.seqera.tower.cli.commands.AbstractApiCmd;
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.responses.roles.RoleAdded;
+import io.seqera.tower.model.CreateRoleRequest;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+import java.util.List;
+
+@Command(
+        name = "add",
+        description = "Add a custom role"
+)
+public class AddCmd extends AbstractApiCmd {
+
+    @Option(names = {"-o", "--organization"}, description = "Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'.", required = true)
+    public String organizationRef;
+
+    @Option(names = {"-n", "--name"}, description = "Custom role name. Must be unique within the organization and different from the predefined role names.", required = true)
+    public String name;
+
+    @Option(names = {"-d", "--description"}, description = "Custom role description (max 120 characters).", required = true)
+    public String description;
+
+    @Option(names = {"-p", "--permissions"}, split = ",", description = "Comma-separated list of permissions granted by the role. See 'tw roles permissions' for the available names.", required = true)
+    public List<String> permissions;
+
+    @Override
+    protected Response exec() throws ApiException {
+        Long orgId = findOrganizationByRef(organizationRef).getOrgId();
+
+        CreateRoleRequest request = new CreateRoleRequest()
+                .name(name)
+                .description(description)
+                .permissions(permissions);
+
+        rolesApi().createRole(request, orgId);
+
+        return new RoleAdded(organizationRef, name);
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/commands/roles/DeleteCmd.java b/src/main/java/io/seqera/tower/cli/commands/roles/DeleteCmd.java
new file mode 100644
index 000000000..70d10aca9
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/commands/roles/DeleteCmd.java
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.commands.roles;
+
+import io.seqera.tower.ApiException;
+import io.seqera.tower.cli.commands.AbstractApiCmd;
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.responses.roles.RoleDeleted;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+@Command(
+        name = "delete",
+        description = "Delete a custom role"
+)
+public class DeleteCmd extends AbstractApiCmd {
+
+    @Option(names = {"-o", "--organization"}, description = "Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'.", required = true)
+    public String organizationRef;
+
+    @Option(names = {"-n", "--name"}, description = "Custom role name.", required = true)
+    public String name;
+
+    @Override
+    protected Response exec() throws ApiException {
+        Long orgId = findOrganizationByRef(organizationRef).getOrgId();
+        rolesApi().deleteRole(name, orgId);
+        return new RoleDeleted(organizationRef, name);
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/commands/roles/ListCmd.java b/src/main/java/io/seqera/tower/cli/commands/roles/ListCmd.java
new file mode 100644
index 000000000..3d95e2277
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/commands/roles/ListCmd.java
@@ -0,0 +1,59 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.commands.roles;
+
+import io.seqera.tower.ApiException;
+import io.seqera.tower.cli.commands.AbstractApiCmd;
+import io.seqera.tower.cli.commands.global.PaginationOptions;
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.responses.roles.RolesList;
+import io.seqera.tower.cli.utils.PaginationInfo;
+import io.seqera.tower.model.ListRolesResponse;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Mixin;
+import picocli.CommandLine.Option;
+
+@Command(
+        name = "list",
+        description = "List predefined and custom roles"
+)
+public class ListCmd extends AbstractApiCmd {
+
+    @Option(names = {"-o", "--organization"}, description = "Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'.", required = true)
+    public String organizationRef;
+
+    @Option(names = {"-t", "--type"}, description = "Role type to list (predefined or custom).")
+    public String type;
+
+    @Option(names = {"-f", "--filter"}, description = "Show only roles whose name contains the given text (* wildcards allowed).")
+    public String filter;
+
+    @Mixin
+    PaginationOptions paginationOptions;
+
+    @Override
+    protected Response exec() throws ApiException {
+        Integer max = PaginationOptions.getMax(paginationOptions);
+        Integer offset = PaginationOptions.getOffset(paginationOptions, max);
+
+        Long orgId = findOrganizationByRef(organizationRef).getOrgId();
+        ListRolesResponse response = rolesApi().listRoles(orgId, max, offset, filter, type);
+
+        Long total = response.getTotalSize() == null ? null : response.getTotalSize().longValue();
+        return new RolesList(organizationRef, response.getRoles(), PaginationInfo.from(paginationOptions, total));
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/commands/roles/PermissionsCmd.java b/src/main/java/io/seqera/tower/cli/commands/roles/PermissionsCmd.java
new file mode 100644
index 000000000..a73b4ba8a
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/commands/roles/PermissionsCmd.java
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.commands.roles;
+
+import io.seqera.tower.ApiException;
+import io.seqera.tower.cli.commands.AbstractApiCmd;
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.responses.roles.RolePermissionsList;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+@Command(
+        name = "permissions",
+        description = "List the permissions that can be granted by a custom role"
+)
+public class PermissionsCmd extends AbstractApiCmd {
+
+    @Option(names = {"-o", "--organization"}, description = "Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'.", required = true)
+    public String organizationRef;
+
+    @Override
+    protected Response exec() throws ApiException {
+        Long orgId = findOrganizationByRef(organizationRef).getOrgId();
+        // The name filter is typed as int64 in the API spec, so it can't carry a search text
+        return new RolePermissionsList(rolesApi().listRolePermissions(orgId, null).getPermissions());
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/commands/roles/UpdateCmd.java b/src/main/java/io/seqera/tower/cli/commands/roles/UpdateCmd.java
new file mode 100644
index 000000000..0832918f8
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/commands/roles/UpdateCmd.java
@@ -0,0 +1,66 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.commands.roles;
+
+import io.seqera.tower.ApiException;
+import io.seqera.tower.cli.commands.AbstractApiCmd;
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.responses.roles.RoleUpdated;
+import io.seqera.tower.model.RoleDto;
+import io.seqera.tower.model.UpdateRoleRequest;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+import java.util.List;
+
+@Command(
+        name = "update",
+        description = "Update a custom role"
+)
+public class UpdateCmd extends AbstractApiCmd {
+
+    @Option(names = {"-o", "--organization"}, description = "Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'.", required = true)
+    public String organizationRef;
+
+    @Option(names = {"-n", "--name"}, description = "Custom role name.", required = true)
+    public String name;
+
+    @Option(names = {"--new-name"}, description = "New custom role name.")
+    public String newName;
+
+    @Option(names = {"-d", "--description"}, description = "New custom role description (max 120 characters).")
+    public String description;
+
+    @Option(names = {"-p", "--permissions"}, split = ",", description = "Comma-separated list of permissions. Replaces the current permissions of the role.")
+    public List<String> permissions;
+
+    @Override
+    protected Response exec() throws ApiException {
+        Long orgId = findOrganizationByRef(organizationRef).getOrgId();
+        RoleDto role = rolesApi().describeRole(name, orgId).getRole();
+
+        // The API replaces name, description and permissions, so unset options keep the current values
+        UpdateRoleRequest request = new UpdateRoleRequest()
+                .name(newName != null ? newName : role.getName())
+                .description(description != null ? description : role.getDescription())
+                .permissions(permissions != null ? permissions : role.getPermissions());
+
+        rolesApi().updateRole(name, request, orgId);
+
+        return new RoleUpdated(organizationRef, request.getName());
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/commands/roles/ViewCmd.java b/src/main/java/io/seqera/tower/cli/commands/roles/ViewCmd.java
new file mode 100644
index 000000000..3f8a7eac1
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/commands/roles/ViewCmd.java
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.commands.roles;
+
+import io.seqera.tower.ApiException;
+import io.seqera.tower.cli.commands.AbstractApiCmd;
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.responses.roles.RoleView;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+@Command(
+        name = "view",
+        description = "View a role and its permissions"
+)
+public class ViewCmd extends AbstractApiCmd {
+
+    @Option(names = {"-o", "--organization"}, description = "Organization name or numeric ID. Specify either the unique organization name or the numeric organization ID returned by 'tw organizations list'.", required = true)
+    public String organizationRef;
+
+    @Option(names = {"-n", "--name"}, description = "Role name.", required = true)
+    public String name;
+
+    @Override
+    protected Response exec() throws ApiException {
+        Long orgId = findOrganizationByRef(organizationRef).getOrgId();
+        return new RoleView(organizationRef, rolesApi().describeRole(name, orgId).getRole());
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/responses/roles/RoleAdded.java b/src/main/java/io/seqera/tower/cli/responses/roles/RoleAdded.java
new file mode 100644
index 000000000..3e0285c6b
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/responses/roles/RoleAdded.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.responses.roles;
+
+import io.seqera.tower.cli.responses.Response;
+
+public class RoleAdded extends Response {
+
+    public final String organizationName;
+    public final String roleName;
+
+    public RoleAdded(String organizationName, String roleName) {
+        this.organizationName = organizationName;
+        this.roleName = roleName;
+    }
+
+    @Override
+    public String toString() {
+        return ansi(String.format("%n  @|yellow Custom role '%s' added to %s organization|@%n", roleName, organizationName));
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/responses/roles/RoleDeleted.java b/src/main/java/io/seqera/tower/cli/responses/roles/RoleDeleted.java
new file mode 100644
index 000000000..845521ef0
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/responses/roles/RoleDeleted.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.responses.roles;
+
+import io.seqera.tower.cli.responses.Response;
+
+public class RoleDeleted extends Response {
+
+    public final String organizationName;
+    public final String roleName;
+
+    public RoleDeleted(String organizationName, String roleName) {
+        this.organizationName = organizationName;
+        this.roleName = roleName;
+    }
+
+    @Override
+    public String toString() {
+        return ansi(String.format("%n  @|yellow Custom role '%s' deleted at %s organization|@%n", roleName, organizationName));
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/responses/roles/RolePermissionsList.java b/src/main/java/io/seqera/tower/cli/responses/roles/RolePermissionsList.java
new file mode 100644
index 000000000..9c6f4b3bf
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/responses/roles/RolePermissionsList.java
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.responses.roles;
+
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.utils.TableList;
+import io.seqera.tower.model.RolePermissionResponseDto;
+
+import java.io.PrintWriter;
+import java.util.List;
+
+public class RolePermissionsList extends Response {
+
+    public final List<RolePermissionResponseDto> permissions;
+
+    public RolePermissionsList(List<RolePermissionResponseDto> permissions) {
+        this.permissions = permissions;
+    }
+
+    @Override
+    public void toString(PrintWriter out) {
+        out.println(ansi(String.format("%n  @|bold Role permissions:|@%n")));
+
+        if (permissions == null || permissions.isEmpty()) {
+            out.println(ansi("    @|yellow No permissions found|@"));
+            return;
+        }
+
+        TableList table = new TableList(out, 2, "Category", "Name");
+        table.setPrefix("    ");
+        permissions.forEach(permission -> table.addRow(permission.getCategory(), permission.getName()));
+        table.print();
+        out.println("");
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/responses/roles/RoleUpdated.java b/src/main/java/io/seqera/tower/cli/responses/roles/RoleUpdated.java
new file mode 100644
index 000000000..489437bee
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/responses/roles/RoleUpdated.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.responses.roles;
+
+import io.seqera.tower.cli.responses.Response;
+
+public class RoleUpdated extends Response {
+
+    public final String organizationName;
+    public final String roleName;
+
+    public RoleUpdated(String organizationName, String roleName) {
+        this.organizationName = organizationName;
+        this.roleName = roleName;
+    }
+
+    @Override
+    public String toString() {
+        return ansi(String.format("%n  @|yellow Custom role '%s' updated at %s organization|@%n", roleName, organizationName));
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/responses/roles/RoleView.java b/src/main/java/io/seqera/tower/cli/responses/roles/RoleView.java
new file mode 100644
index 000000000..11b00938f
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/responses/roles/RoleView.java
@@ -0,0 +1,53 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.responses.roles;
+
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.utils.TableList;
+import io.seqera.tower.model.RoleDto;
+
+import java.io.PrintWriter;
+
+public class RoleView extends Response {
+
+    public final String organizationName;
+    public final RoleDto role;
+
+    public RoleView(String organizationName, RoleDto role) {
+        this.organizationName = organizationName;
+        this.role = role;
+    }
+
+    @Override
+    public void toString(PrintWriter out) {
+        out.println(ansi(String.format("%n  @|bold Role '%s' at %s organization:|@%n", role.getName(), organizationName)));
+        TableList table = new TableList(out, 2);
+        table.setPrefix("    ");
+        table.addRow("Name", role.getName());
+        table.addRow("Type", Boolean.TRUE.equals(role.getIsPredefined()) ? "predefined" : "custom");
+        table.addRow("Description", role.getDescription());
+        table.print();
+
+        out.println(ansi(String.format("%n  @|bold Permissions:|@%n")));
+        if (role.getPermissions() == null || role.getPermissions().isEmpty()) {
+            out.println(ansi("    @|yellow No permissions found|@"));
+            return;
+        }
+        role.getPermissions().forEach(permission -> out.println("    " + permission));
+        out.println("");
+    }
+}
diff --git a/src/main/java/io/seqera/tower/cli/responses/roles/RolesList.java b/src/main/java/io/seqera/tower/cli/responses/roles/RolesList.java
new file mode 100644
index 000000000..de7392d21
--- /dev/null
+++ b/src/main/java/io/seqera/tower/cli/responses/roles/RolesList.java
@@ -0,0 +1,66 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.responses.roles;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import io.seqera.tower.cli.responses.Response;
+import io.seqera.tower.cli.utils.PaginationInfo;
+import io.seqera.tower.cli.utils.TableList;
+import io.seqera.tower.model.ListRolesResponseRoleInfo;
+import jakarta.annotation.Nullable;
+
+import java.io.PrintWriter;
+import java.util.List;
+
+public class RolesList extends Response {
+
+    public final String organizationName;
+    public final List<ListRolesResponseRoleInfo> roles;
+
+    @JsonIgnore
+    @Nullable
+    private final PaginationInfo paginationInfo;
+
+    public RolesList(String organizationName, List<ListRolesResponseRoleInfo> roles, @Nullable PaginationInfo paginationInfo) {
+        this.organizationName = organizationName;
+        this.roles = roles;
+        this.paginationInfo = paginationInfo;
+    }
+
+    @Override
+    public void toString(PrintWriter out) {
+        out.println(ansi(String.format("%n  @|bold Roles for %s organization:|@%n", organizationName)));
+
+        if (roles == null || roles.isEmpty()) {
+            out.println(ansi("    @|yellow No roles found|@"));
+            return;
+        }
+
+        TableList table = new TableList(out, 3, "Name", "Type", "Description");
+        table.setPrefix("    ");
+        roles.forEach(role -> table.addRow(
+                role.getName(),
+                Boolean.TRUE.equals(role.getIsPredefined()) ? "predefined" : "custom",
+                role.getDescription()
+        ));
+        table.print();
+
+        PaginationInfo.addFooter(out, paginationInfo);
+
+        out.println("");
+    }
+}
diff --git a/src/test/java/io/seqera/tower/cli/roles/RolesCmdTest.java b/src/test/java/io/seqera/tower/cli/roles/RolesCmdTest.java
new file mode 100644
index 000000000..90a83bced
--- /dev/null
+++ b/src/test/java/io/seqera/tower/cli/roles/RolesCmdTest.java
@@ -0,0 +1,190 @@
+/*
+ * Copyright 2021-2026, Seqera.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.seqera.tower.cli.roles;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import io.seqera.tower.cli.BaseCmdTest;
+import io.seqera.tower.cli.commands.enums.OutputType;
+import io.seqera.tower.cli.responses.roles.RoleAdded;
+import io.seqera.tower.cli.responses.roles.RoleDeleted;
+import io.seqera.tower.cli.responses.roles.RolePermissionsList;
+import io.seqera.tower.cli.responses.roles.RoleUpdated;
+import io.seqera.tower.cli.responses.roles.RoleView;
+import io.seqera.tower.cli.responses.roles.RolesList;
+import io.seqera.tower.model.DescribeRoleResponse;
+import io.seqera.tower.model.ListRolePermissionsResponse;
+import io.seqera.tower.model.ListRolesResponse;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
+import org.mockserver.client.MockServerClient;
+import org.mockserver.matchers.MatchType;
+import org.mockserver.model.MediaType;
+
+import static io.seqera.tower.cli.utils.JsonHelper.parseJson;
+import static org.mockserver.matchers.Times.exactly;
+import static org.mockserver.model.HttpRequest.request;
+import static org.mockserver.model.HttpResponse.response;
+import static org.mockserver.model.JsonBody.json;
+
+class RolesCmdTest extends BaseCmdTest {
+
+    private static final String ORG_ID = "27736513644467";
+
+    private static final String ROLE = """
+            {"role": {"name": "runner", "description": "Launch only", "isPredefined": false, "permissions": ["pipeline:launch", "workflow:read"]}}
+            """;
+
+    @BeforeEach
+    void mockUserWorkspaces(MockServerClient mock) {
+        mock.when(request().withMethod("GET").withPath("/user-info"))
+                .respond(response().withStatusCode(200).withBody(loadResource("user")).withContentType(MediaType.APPLICATION_JSON));
+        mock.when(request().withMethod("GET").withPath("/user/1264/workspaces"))
+                .respond(response().withStatusCode(200).withBody(loadResource("workspaces/workspaces_list")).withContentType(MediaType.APPLICATION_JSON));
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testList(OutputType format, MockServerClient mock) throws JsonProcessingException {
+        String body = """
+                {"roles": [
+                  {"name": "owner", "description": "Full permissions", "isPredefined": true},
+                  {"name": "runner", "description": "Launch only", "isPredefined": false}
+                ], "totalSize": 2}
+                """;
+        mock.when(
+                request().withMethod("GET").withPath("/roles")
+                        .withQueryStringParameter("orgId", ORG_ID)
+                        .withQueryStringParameter("type", "custom")
+                        .withQueryStringParameter("name", "run")
+                        .withQueryStringParameter("max", "100")
+                        .withQueryStringParameter("offset", "0"), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(body).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "roles", "list", "-o", "organization1", "-t", "custom", "-f", "run");
+
+        assertOutput(format, out, new RolesList("organization1", parseJson(body, ListRolesResponse.class).getRoles(), null));
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testView(OutputType format, MockServerClient mock) throws JsonProcessingException {
+        mock.when(
+                request().withMethod("GET").withPath("/roles/runner").withQueryStringParameter("orgId", ORG_ID), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(ROLE).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "roles", "view", "-o", "organization1", "-n", "runner");
+
+        assertOutput(format, out, new RoleView("organization1", parseJson(ROLE, DescribeRoleResponse.class).getRole()));
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testAdd(OutputType format, MockServerClient mock) {
+        mock.when(
+                request().withMethod("POST").withPath("/roles").withQueryStringParameter("orgId", ORG_ID)
+                        .withBody(json("""
+                                {"name": "runner", "description": "Launch only", "permissions": ["pipeline:launch", "workflow:read"]}
+                                """, MatchType.STRICT)), exactly(1)
+        ).respond(
+                response().withStatusCode(201).withBody(ROLE).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "roles", "add", "-o", "organization1", "-n", "runner", "-d", "Launch only", "-p", "pipeline:launch,workflow:read");
+
+        assertOutput(format, out, new RoleAdded("organization1", "runner"));
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testUpdateKeepsUnsetFields(OutputType format, MockServerClient mock) {
+        mock.when(
+                request().withMethod("GET").withPath("/roles/runner").withQueryStringParameter("orgId", ORG_ID), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(ROLE).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("PUT").withPath("/roles/runner").withQueryStringParameter("orgId", ORG_ID)
+                        .withBody(json("""
+                                {"name": "launcher", "description": "Launch only", "permissions": ["pipeline:launch", "workflow:read"]}
+                                """, MatchType.STRICT)), exactly(1)
+        ).respond(
+                response().withStatusCode(204)
+        );
+
+        ExecOut out = exec(format, mock, "roles", "update", "-o", "organization1", "-n", "runner", "--new-name", "launcher");
+
+        assertOutput(format, out, new RoleUpdated("organization1", "launcher"));
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testUpdateReplacesPermissions(OutputType format, MockServerClient mock) {
+        mock.when(
+                request().withMethod("GET").withPath("/roles/runner").withQueryStringParameter("orgId", ORG_ID), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(ROLE).withContentType(MediaType.APPLICATION_JSON)
+        );
+        mock.when(
+                request().withMethod("PUT").withPath("/roles/runner").withQueryStringParameter("orgId", ORG_ID)
+                        .withBody(json("""
+                                {"name": "runner", "description": "Read only", "permissions": ["workflow:read"]}
+                                """, MatchType.STRICT)), exactly(1)
+        ).respond(
+                response().withStatusCode(204)
+        );
+
+        ExecOut out = exec(format, mock, "roles", "update", "-o", "organization1", "-n", "runner", "-d", "Read only", "-p", "workflow:read");
+
+        assertOutput(format, out, new RoleUpdated("organization1", "runner"));
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testDelete(OutputType format, MockServerClient mock) {
+        mock.when(
+                request().withMethod("DELETE").withPath("/roles/runner").withQueryStringParameter("orgId", ORG_ID), exactly(1)
+        ).respond(
+                response().withStatusCode(204)
+        );
+
+        ExecOut out = exec(format, mock, "roles", "delete", "-o", "organization1", "-n", "runner");
+
+        assertOutput(format, out, new RoleDeleted("organization1", "runner"));
+    }
+
+    @ParameterizedTest
+    @EnumSource(OutputType.class)
+    void testPermissions(OutputType format, MockServerClient mock) throws JsonProcessingException {
+        String body = """
+                {"permissions": [{"name": "pipeline:launch", "category": "Pipelines"}, {"name": "workflow:read", "category": "Runs"}]}
+                """;
+        mock.when(
+                request().withMethod("GET").withPath("/roles/permissions").withQueryStringParameter("orgId", ORG_ID), exactly(1)
+        ).respond(
+                response().withStatusCode(200).withBody(body).withContentType(MediaType.APPLICATION_JSON)
+        );
+
+        ExecOut out = exec(format, mock, "roles", "permissions", "-o", "organization1");
+
+        assertOutput(format, out, new RolePermissionsList(parseJson(body, ListRolePermissionsResponse.class).getPermissions()));
+    }
+}

From 6674bdbc624b6983c25649f9795a0b6a914ab57a Mon Sep 17 00:00:00 2001
From: Cristian Ramon-Cortes <cristian.ramon-cortes@seqera.io>
Date: Wed, 7 Oct 2026 11:37:44 +0200
Subject: [PATCH 6/7] docs: document custom roles, folder mounts and linked
 datasets

A custom roles section, 'tw members roles' next to organization quotas, and summary bullets for studio folder mounts and linked datasets.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 USAGE.md | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/USAGE.md b/USAGE.md
index bc8bce04e..84e08f161 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -713,10 +713,19 @@ $ tw data-links browse -w seqeralabs/showcase -i v1-user-6d8f44c239e2a098b3e02e9
 
 These commands act on an organization (`-o`/`--organization`). Most require the organization `OWNER` role.
 
+### Custom roles
+
+Run `tw roles -h` to view the supported operations: `list`, `view`, `add`, `update`, `delete`, and `permissions`. `tw participants update --role` accepts custom role names.
+
+```bash
+tw roles permissions -o my-org
+tw roles add -o my-org -n launcher -d "Launch only" -p <permission>,<permission>
+```
+
 ### Teams and quotas
 
 - `tw teams view|update|workspaces`: view a team, update its name or description, and list its workspaces.
-- `tw organizations quotas`: view organization quotas.
+- `tw organizations quotas` and `tw members roles -u <user>`: view organization quotas and a member's workspace roles.
 
 ## Personal access
 
@@ -756,9 +765,9 @@ tw managed-identities credentials -o my-org -n hpc1 add -l my_linux_user -k ~/.s
 - `tw launch`, `tw pipelines add|update`, `tw runs relaunch`, and `tw actions add|update`: `--tower-config`.
 - `tw runs star|unstar`, `tw runs view log [--next <cursor>]`, and `tw runs delete -i <id>,<id>`.
 - `tw pipelines schema`: show a pipeline's parameter schema.
-- `tw studios extend|rename-checkpoint`.
+- `tw studios extend|rename-checkpoint`. `--mount-data-uris` also accepts a folder inside a data link.
 - `tw data-links delete-content|download-script`.
-- `tw datasets disable-version`.
+- `tw datasets add --url`, `tw datasets update --url`, and `tw datasets disable-version`.
 
 [compute-envs]: https://docs.seqera.io/platform/latest/compute-envs/overview
 [credentials]: https://docs.seqera.io/platform/latest/credentials/overview

From 24cb0df7d81ed2245d059d0175ea39d519a611ac Mon Sep 17 00:00:00 2001
From: Cristian Ramon-Cortes <cristian.ramon-cortes@seqera.io>
Date: Wed, 7 Oct 2026 16:48:57 +0200
Subject: [PATCH 7/7] build(native): register reflection metadata for the roles
 commands

Entries for the roles and members roles commands and responses, taken from a full test run under the GraalVM tracing agent. Response classes register allDeclaredFields, since Jackson serializes every field for -o json.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 conf/reflect-config.json | 99 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/conf/reflect-config.json b/conf/reflect-config.json
index c859a2a9d..a162cd754 100644
--- a/conf/reflect-config.json
+++ b/conf/reflect-config.json
@@ -250,6 +250,12 @@
   "allDeclaredMethods":true,
   "methods":[{"name":"<init>","parameterTypes":[] }]
 },
+{
+  "name":"io.seqera.tower.cli.commands.RolesCmd",
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true,
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
 {
   "name":"io.seqera.tower.cli.commands.RunsCmd",
   "allDeclaredFields":true,
@@ -1614,6 +1620,13 @@
   "allDeclaredMethods":true,
   "methods":[{"name":"<init>","parameterTypes":[] }]
 },
+{
+  "name":"io.seqera.tower.cli.commands.members.RolesCmd",
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true,
+  "fields":[{"name":"organizationRef"}, {"name":"user"}],
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
 {
   "name":"io.seqera.tower.cli.commands.members.UpdateCmd",
   "allDeclaredFields":true,
@@ -1859,6 +1872,48 @@
   "queryAllDeclaredMethods":true,
   "methods":[{"name":"<init>","parameterTypes":[] }]
 },
+{
+  "name":"io.seqera.tower.cli.commands.roles.AddCmd",
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true,
+  "fields":[{"name":"description"}, {"name":"name"}, {"name":"organizationRef"}, {"name":"permissions"}],
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
+{
+  "name":"io.seqera.tower.cli.commands.roles.DeleteCmd",
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true,
+  "fields":[{"name":"name"}, {"name":"organizationRef"}],
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
+{
+  "name":"io.seqera.tower.cli.commands.roles.ListCmd",
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true,
+  "fields":[{"name":"filter"}, {"name":"organizationRef"}, {"name":"paginationOptions"}, {"name":"type"}],
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
+{
+  "name":"io.seqera.tower.cli.commands.roles.PermissionsCmd",
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true,
+  "fields":[{"name":"organizationRef"}],
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
+{
+  "name":"io.seqera.tower.cli.commands.roles.UpdateCmd",
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true,
+  "fields":[{"name":"description"}, {"name":"name"}, {"name":"newName"}, {"name":"organizationRef"}, {"name":"permissions"}],
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
+{
+  "name":"io.seqera.tower.cli.commands.roles.ViewCmd",
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true,
+  "fields":[{"name":"name"}, {"name":"organizationRef"}],
+  "methods":[{"name":"<init>","parameterTypes":[] }]
+},
 {
   "name":"io.seqera.tower.cli.commands.runs.AbstractRunsCmd",
   "allDeclaredFields":true,
@@ -2741,6 +2796,14 @@
   "queryAllDeclaredMethods":true,
   "queryAllDeclaredConstructors":true
 },
+{
+  "name":"io.seqera.tower.cli.responses.members.MemberRolesList",
+  "allDeclaredFields":true,
+  "allDeclaredMethods":true,
+  "allDeclaredConstructors":true,
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true
+},
 {
   "name":"io.seqera.tower.cli.responses.members.MembersAdded",
   "allDeclaredFields":true,
@@ -2907,6 +2970,42 @@
   "queryAllDeclaredMethods":true,
   "queryAllDeclaredConstructors":true
 },
+{
+  "name":"io.seqera.tower.cli.responses.roles.RoleAdded",
+  "allDeclaredFields":true,
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true
+},
+{
+  "name":"io.seqera.tower.cli.responses.roles.RoleDeleted",
+  "allDeclaredFields":true,
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true
+},
+{
+  "name":"io.seqera.tower.cli.responses.roles.RolePermissionsList",
+  "allDeclaredFields":true,
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true
+},
+{
+  "name":"io.seqera.tower.cli.responses.roles.RoleUpdated",
+  "allDeclaredFields":true,
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true
+},
+{
+  "name":"io.seqera.tower.cli.responses.roles.RoleView",
+  "allDeclaredFields":true,
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true
+},
+{
+  "name":"io.seqera.tower.cli.responses.roles.RolesList",
+  "allDeclaredFields":true,
+  "queryAllDeclaredMethods":true,
+  "queryAllDeclaredConstructors":true
+},
 {
   "name":"io.seqera.tower.cli.responses.runs.RunCanceled",
   "allDeclaredFields":true,