# Sharing Commands

## Commands

#### Keeper Command Reference

Whether using the interactive shell, CLI or JSON config file, Keeper supports the following commands, each command supports additional parameters and options.

To get help on a particular command, run:

`help <command>`

### **Sharing Commands**

| Command                                                              | Explanation                                |
| -------------------------------------------------------------------- | ------------------------------------------ |
| [`share-record`](#share-record-command) or `sr`                      | Grant or revoke user access to a record    |
| [`share-folder`](#share-folder-command) or `sf`                      | Change shared folder permissions           |
| [`record-permission`](#record-permission-command)                    | Change record permissions of a folder      |
| [`one-time-share`](#share-command)                                   | Manage one-time shares                     |
| [`external-shares-report`](#external-shares-report-command) or `esr` | Display or revoke shares to external users |

### share-record command

**Command:** `share-record` or `sr`

**Detail:** Grant or revoke user access to record(s) given that record or folder path or UID

**Parameters:**

Path or UID of record or folder

**Switches:**

-e, --email \<EMAIL> email of account to edit permissions for (required)

-a, --action <{*grant, revoke, owner, cancel*}> permission to set for record

-s, --share allow user to share record

-w, --write allow user to modify record

-R, --recursive apply command to shared folder hierarchy

\--dry-run  display the permissions changes without committing them

\--expire-at EXPIRE\_AT  share expiration: "never" or ISO date-time (yyyy-MM-dd\[ hh:mm:ss])

\--expire-in \<NUMBER>\[(mi)nutes|(h)ours|(d)ays|(mo)nths|(y)ears]  share expiration: "never" or period

\--contacts-only  share only to known targets. Allows routing to alternate domains with matching usernames if needed

-f, --force skip confirmation prompts

**Examples:**

```
share-record memberships/Gym -e john.smith@gmail.com
sr g6rvo2-Uv-BC16ZM33CF3w -e john.smith@gmail.com --share
sr social/Twitter -e john.smith@gmail.com --action owner
sr --recursive -e john.smith@gmail.com "My Shared Folder" 
sr --expire-at "2050-01-01 00:00:01" -e john.smith@gmail.com memberships/Gym
sr --expire-in 3d -e john.smith@gmail.com social/Twitter
sr --contacts-only -e bob.dobb@wrongdomain.com 'Wifi Credentials'
```

1. Share the "Gym" record in the "memberships" folder with user John Smith
2. Share a record with the given UID with user John Smith and allow him to share the record with others
3. Transfer record ownership of the "Twitter" records from the "social" folder with user John Smith
4. Share all records found in shared-folder "My Shared Folder" (including any in its subfolders) with user John Smith
5. Share record "Gym" in the "memberships" folder with user John Smith, accessible until 1 second after the start of the year 2050 (GMT)   &#x20;
6. Give user John Smith time-limited read-only access (valid only for the next 3 days) to the "Twitter" record in the folder named "social"
7. Share record 'Wifi Credentials' with the specified user, but only after checking the share recipient against known share targets and substituting — if appropriate — a corresponding *known* username (w/ a different domain) for those w/ no known exact match. In this example, if ***<bob.dobb@rightdomain.com>*** is a known share target but the provided username is not, the calling user would be prompted to confirm before substituting the former for the latter when creating the sharing relationship.\
   Hint: you can skip the confirmation prompt by including the `--force`option.

### share-folder command

**Command:** `share-folder` or `sf`

**Detail:** Grant or revoke user default permissions for a given (set of) shared folder(s)

{% hint style="info" %}
See the [mkdir ](https://docs.keeper.io/en/keeperpam/commander-cli/record-commands#mkdir-command)command for details on creating shared folders
{% endhint %}

**Parameters:**

Path(s) or UID(s) of folder(s)

**Switches:**

-a, --action <{*grant, remove*}> permission to set for folder(s) / record(s)

-e, --email \<EMAIL, TEAM, \*>

* email - user's email to set folder permissions for
* team - name of a team to set folder permissions for
* \* - apply relevant permissions for each new user with whom the folder(s) is/are shared
* @currrent/@existing - apply to all users with existing access to folder(s)&#x20;

-r, --record <{RECORD NAME, UID, \*, @existing, @current}>

* record name / UID - specific record to set permissions for
* \* - set default permissions for any new record added to the relevant folder(s)
* @existing/@current - apply permissions to all records currently contained by the specified shared folder(s)

-p, --manage-records toggles the permission to manage records with `on` or `off`. Users/teams only

-o, --manage-users toggles the permission to manage users with `on` or `off`. Users/teams only

-s, --can-share toggles the permission to share records with `on` or `off`. Records only

-d, --can-edit toggles the permission to modify records with `on` or `off`. Records only

-f, --force apply permissions changes ignoring default folder permissions

\--expire-at TIMESTAMP  share expiration: "never" or ISO date-time (yyyy-MM-dd\[ hh:mm:ss])

\--expire-in PERIOD  share expiration: "never" or period (\<NUMBER>\[(y)ears|(mo)nths|(d)ays|(h)ours(mi)nutes])

**Examples:**

```
share-folder memberships -e Jane.Smith@gmail.com -p off
sf jdrkYEaf03bG0ShCGlnKww -e DB_ADMINS -p on
sf "Team Passwords" -e "Marketing Team" -a grant -o on
sf * -e DB_ADMINS -p on
sf -a remove -e Jane.Smith@gmail.com memberships
sf -e Jane.Smith@gmail.com --expire-in 5h memberships
```

1. Share the "memberships" shared folder with user <Jane.Smith@gmail.com>.  Allow the user to manage records
2. Share the folder with the given UID with the "DB\_ADMINS" team and allow them to manage records in the shared folder
3. Share a "Team Passwords" folder with a team called "Marketing Team" and give permission to manage users
4. Share all shared folders with the "DB\_ADMINS" team and allow them to manage records in the shared folder&#x20;
5. Remove all access to "memberships" shared folder for user ***Jane.Smith\@gmail***&#x20;
6. Grant user read-only access to "memberships" shared-folder, valid only for the next 5 hours

#### Changing Default Folder Settings

The Default Folder Settings control the permissions on newly added users and records. To change the default permissions with the `share-folder` command, use the \[\*] symbol.&#x20;

For example, to set user defaults to "Can Manage Users & Records" and to set record defaults to "Can Edit & Share" on the Shared Folder based on a UID:

{% code overflow="wrap" %}

```
sf --email=* --manage-users on --manage-records on jdrkYEaf03bG0ShCGlnKww
sf --record=* --can-share on --can-edit on jdrkYEaf03bG0ShCGlnKww
```

{% endcode %}

{% hint style="info" %}
Hint: You can also apply the same permissions used to set a shared folder's default settings (as in the examples above) to records/users currently assigned to that shared folder within the same command call by simply specifying the value "@current" or "@existing" for the appropriate option/s (-r for records, -e for users). Using examples similar to the ones above, we have the following:

```
sf -e * --manage-users on --manage-records on -e @existing memberships
sf -r * --can-share on --can-edit on -r @existing -e @existing memberships
```

In the 1st example, we set both the default user permissions and the permissions granted to current users assigned to the shared folder to "can manage users" and "can manage records".

In the 2nd example, we set both default record permissions and permissions for already-existing records currently contained by the shared-folder to "can edit" and "can share' for users that currently have access to that shared-folder &#x20;
{% endhint %}

### record-permission command

**Detail:** Change the permissions for all records in a shared folder

**Parameters:**

Path or UID of folder

**Switches:**

-a, --action <{*grant, revoke*}> permission access to set for record

-s, --can-share allow sharing records

-d, --can-edit allow modifying records in the folder

-f, --force apply permissions changes without prompting&#x20;

-R, --recursive apply permission changes to all sub folders&#x20;

\--dry-run Display permission changes made by command without actually changing the permissions

\--share-record change a record's sharing permissions

\--share-folder change a folder's sharing permissions

**Examples:**

```
record-permission memberships --action grant --can-share
record-permission jdrkYEaf03bG0ShCGlnKww -a revoke -d -R
record-permission social -a grant -s --dry-run
```

1. Grant sharing permission to all records in the "memberships" shared folder
2. Revoke edit permission from all records in the folder with the given UID and all sub folders
3. See the changes that would be made by granting sharing permissions to the "social" folder but don't apply the permission change

### share Command

{% hint style="info" %}
Requires Commander version 16.6.3+
{% endhint %}

**Command:** `one-time-share`

**Detail:** Create, list, or remove a one-time shares for a given record. [Learn more](https://app.gitbook.com/s/-LO5CAzpxoaEquZJBpYz/sharing/one-time-share) about one-time share.

**Sub Commands:**

`list` - show one time shares

`create` - create a new one time share URL

`remove` - remove a one time share

**List**

**Switches:**

`-a` `--all` show all one-time shares, including expired shares

`--format <table, csv, json>` the format to show the one time shares in

`-v` `--verbose` Verbose output

`-R --recursive` Traverse recursively through subfolders

**Parameters:**

* name or UID of record or folder. Can be repeated

**Create**

**Switches:**

`--output <clipboard, stdout>` choose to put the URL in the clipboard, or to stdout (default)

`--name` name the one time share

`-e <TIME>`  `--expire <TIME>`  how long the one time share will remain active

&#x20;   format: \<NUMBER>\[(mi)nutes|(h)ours|(d)ays] e.g. `1h` for 1 hour

`--editable` Allow recipient to edit record fields and upload files

**Parameters:**

* name or UID of record. Can be repeated

**Remove**

**Parameters:**

* name or UID of record
* one-time share name or ID&#x20;

**Examples:**

**List**

```
My Vault> one-time-share list -R /
My Vault> ots list dIGd46nq2uE_q1fXlAQGkw --all
Record UID              Name         Share Link ID            Generated            Opened    Expires              Status
----------------------  -----------  -----------------------  -------------------  --------  -------------------  ---------
dIGyf6nq2uE_q1fXlAQGkw  MyShare      vhSIl2fnjp5tTaE4w9DC...  2022-04-29 11:01:19            2022-04-29 12:01:19  Expired
dIGyf6nq2uE_q1fXlAQGkw  LwIdbnYa160  bOuAQzCoYL8XIcQpz2KU...  2022-04-29 15:38:27            2022-04-29 16:38:27  Generated
```

**Create**

```
My Vault> share create dIGyf6nq2uE_q1fXlAQGkw -e 1h
       URL : https://keepersecurity.com/vault/share#s4iSKc7TP[...]
```

**Create with Bidirectional Edit**

```
My Vault> share create --editable dIGyf6nq2uE_q1fXlAQGkw -e 1h
       URL : https://keepersecurity.com/vault/share#s4iSKc7TP[...]
```

**Remove**

```
My Vault> share remove dIGyf6nq2uE_q1fXlAQGkw MyShare
One-time share "MyShare" is removed from record "dIGyf6nq2uE_q1fXlAQGkw"
```

### external-shares-report command

{% hint style="info" %}
The external-shares-report requires the [Compliance Reporting](https://docs.keeper.io/enterprise-guide/compliance-reports) add-on. This command is only available for Enterprise admin accounts.
{% endhint %}

**Command:** `external-shares-report` or `esr`

**Details:** Display and (optionally) revoke share-permissions granted to users outside of the enterprise

**Switches:**

\--format <{table, json, csv}> format the output, default is 'table'

\--output \<FILENAME> output to a filename. Ignored with 'table' format

\--action, -a <{remove, none}> action to perform on external shares, 'none' if omitted

\--share-type, -t <{direct, shared-folder, all}> filter report by share type, 'all' if omitted

\--force, -f, skip confirmation when removing shares

\--refresh-data, -r refresh local user and record data before running

**Examples:**

```
external-shares-report
external-shares-report -r
esr --output external_shares.json --format json
external-shares-report -a remove
esr -a remove -f
external-shares-report --share-type shared-folder
```

1. Show records and shared-folders shared to users outside of the enterprise
2. Refresh locally-cached enterprise record/folder/user data prior to running and showing report
3. Run report and export results to a JSON-formatted file named ***external\_shares.json***
4. Run report, show results, and revoke external shares identified in the results&#x20;
5. Same as #4 above but requires no additional user-interaction to complete execution (i.e., skips confirmation prompt prior to revoking the external shares identified in the report)
6. Run and show report, limiting results to records shared via direct-share (i.e., omit shared-folders from report)

{% hint style="info" %}
By default, using the above command to revoke share-permissions previously granted to external accounts (via `esr -a remove`) requires user-interaction -- via a confirmation prompt -- to complete.

**Hint**: If you need to perform this task in a non-interactive manner (e.g., if running from a Keeper script/batch file, or as part of an automated administrative tool), include the `--force` flag in your command call (e.g., `external-shares-report --force --action remove`)&#x20;
{% endhint %}

### Bulk Record Permission Changes

In this example, we will recursively change the record permissions in a Shared Folder.

#### 1. Identify Shared Folder UID

On Commander, you can use the "ls -l" command, similar to a Bash shell.

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MejtIk9t2VrzvkI15rE%2F-MekzeEjeziNtK3guRXA%2Fimage.png?alt=media\&token=033f1c23-92c6-4f8c-a1f7-9415d9e96463)

On the Vault user interface, you can click on the info dialog to get the Shared Folder UID.

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MejtIk9t2VrzvkI15rE%2F-Mekzvgfxbk98bpbGFh_%2Fimage.png?alt=media\&token=32c6aa29-85cd-4de6-a2d7-318085088a5f)

#### **2. Validate Record Permissions Change with Commander**

With Commander, execute the `record-permission` command with the `--dry-run` option to simulate the command.  In this example, the Shared Folder UID is "-FHdesR\_GSERHUwBg4vTXw".  The command is below:\
\
**record-permission --dry-run --recursive --action grant --can-edit -- -FHdesR\_GSERHUwBg4vTXw**

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MejtIk9t2VrzvkI15rE%2F-Mel-_yS8GDbOy4_Cd0W%2Fimage.png?alt=media\&token=3ff3d195-2db6-4d93-91ab-97dc3ff01210)

{% hint style="info" %}
Since the Shared Folder UID beings with '-' in this example, '--' must be added before the identifier
{% endhint %}

Running this command produces the following output:

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MejtIk9t2VrzvkI15rE%2F-Mel02MSVQayPfXmhqbT%2Fimage.png?alt=media\&token=4813048e-99f3-4238-ab10-aacf9ce446d4)

The "SKIP" section is saying that the current user on Commander cannot make those requested changes, because we are not the owner of the record.  The "GRANT" section indicates the changes that will be allowed.

#### **3. Execute Permissions Change Command with Commander**

To execute the command, we remove the "--dry-run" portion:

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MejtIk9t2VrzvkI15rE%2F-Mel0U6AJJFYFrnwhdyL%2Fimage.png?alt=media\&token=14e6b9f2-53fe-4c82-9c99-d6b477732436)

Now, on the Vault UI, the permission of those affected records has been changed to "Can Edit".

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MejtIk9t2VrzvkI15rE%2F-Mel0Z9xJp1m7dxf1H8C%2Fimage.png?alt=media\&token=0c2a9f0e-5f49-4a4b-8fd1-235a3094af72)

#### Shared Folders With Multiple Record Owners

If you are in a situation with many record owners in the same shared folder that require update, each of those users can simply run the above Commander action to change the permissions of their respective records.

{% hint style="info" %}
Hint:&#x20;

If you are an enterprise-user with share-admin privileges, you need only perform the steps outlined above once to change permissions for all records (regardless of who owns those records) in the shared-folder.&#x20;

In such a case, there is no need for other record-owners to repeat the same steps, thus greatly simplifying the process.
{% endhint %}

### Bulk Record-Ownership Transfer

Using steps *almost* identical to those of the previous example (in which we show how to change permissions for all records within a shared folder), it is also possible to transfer ownership of all records within a given shared folder to a single account.

For the following example (using the same vault and shared folder as the previous example), let's assume that we would like to transfer ownership of the records in that shared folder to user ***<joe.smith@gmail.com>***. The steps are as follows:&#x20;

#### 1. Identify Shared Folder UID

See previous [example](#1.-identify-shared-folder-uid) for details on how to do this. For this example, we'll be using the shared folder with UID **`-FHdesR_GSERHUwBg4vTXw`**

#### **2. Validate Record-Ownership Transfer Command with Commander**

Similar to the previous example, we can simulate the desired action prior to its actual execution by running the `share-record` command with the `--dry-run` option in Commander (Note: unlike the previous example, we will also need to specify the username -- ***<john.smith@gmail.com>*** in this example -- for the account to which ownership of records should be transferred). The command is as follows:

**`share-record --action owner --email john.smith@gmail.com --dry-run --recursive -- -FHdesR_GSERHUwBg4vTXw`**

#### **3. Execute Record-Ownership Transfer Command with Commander**

Finally, as in the previous example, we remove the `--dry-run` option from our command call to perform the desired action, like so:

**`share-record --action owner --email john.smith@gmail.com --recursive -- -FHdesR_GSERHUwBg4vTXw`**
