---
layout: default
navsection: admin
title: Role group management at the CLI
...

{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.

SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}

This page describes how to manage groups at the command line.  You should be familiar with the "permission system":{{site.baseurl}}/api/permission-model.html .

h2. Create a role group

User groups are entries in the "groups" table with @"group_class": "role"@.

<pre>
arv group create --group '{"name": "My new group", "group_class": "role"}'
</pre>

h2(#add). Add a user to a role group

There are two separate permissions associated with group membership.  The first link grants the user @can_manage@ permission to manage things that the group can manage.  The second link grants permission for other users of the group to see that this user is part of the group.

<pre>
arv link create --link '{
  "link_class": "permission",
  "name": "can_manage",
  "tail_uuid": "the_user_uuid",
  "head_uuid": "the_group_uuid"}'

arv link create --link '{
  "link_class": "permission",
  "name": "can_read",
  "tail_uuid": "the_group_uuid",
  "head_uuid": "the_user_uuid"}'
</pre>

A user can also be given read-only access to a group.  In that case, the first link should be created with @can_read@ instead of @can_manage@.

h2. List role groups

<pre>
arv group list --filters '[["group_class", "=", "role"]]'
</pre>

h2. List members of a role group

Use the command "jq":https://stedolan.github.io/jq/ to extract the tail_uuid of each permission link which has the user uuid.

<pre>
arv link list --filters '[["link_class", "=", "permission"],
  ["head_uuid", "=", "the_group_uuid"]]' | jq .items[].tail_uuid
</pre>

h2(#share-project). Share a project with a role group

Members of the role group will have access to the project based on their level of access to the role group.

<pre>
arv link create --link '{
  "link_class": "permission",
  "name": "can_manage",
  "tail_uuid": "the_group_uuid",
  "head_uuid": "the_project_uuid"}'
</pre>

A project can also be shared read-only.  In that case, the link @name@ should be @can_read@ instead of @can_manage@.

h2. List things shared with the group

Use the command "jq":https://stedolan.github.io/jq/ to extract the head_uuid of each permission link which has the object uuid.

<pre>
arv link list --filters '[["link_class", "=", "permission"],
  ["tail_uuid", "=", "the_group_uuid"]]' | jq .items[].head_uuid
</pre>

h2(#stop-sharing-project). Stop sharing a project with a group

This will remove access for members of the group.

The first step is to find the permission link objects.  The second step is to delete them.

<pre>
arv --format=uuid link list --filters '[["link_class", "=", "permission"],
  ["tail_uuid", "=", "the_group_uuid"], ["head_uuid", "=", "the_project_uuid"]]'

arv link delete --uuid each_link_uuid
</pre>

h2. Remove user from a role group

The first step is to find the permission link objects.  The second step is to delete them.

<pre>
arv --format=uuid link list --filters '[["link_class", "=", "permission"],
  ["tail_uuid", "in", ["the_user_uuid", "the_group_uuid"]],
  ["head_uuid", "in", ["the_user_uuid", "the_group_uuid"]]'

arv link delete --uuid each_link_uuid
</pre>