# Folder Command

## `folder` command

**Description:** List, create, update and delete folders from the vault. Works only within folders shared to KSM Applications. The folder command manages subfolders within existing shared folders.

**Parameters:**

Sub-command to run

format: **`ksm folder <sub-command>`**

**Sub-Commands:**

| Sub-Command | Description                                      |
| ----------- | ------------------------------------------------ |
| `list`      | List all folders associated with the application |
| `add`       | Add a new subfolder to the vault.                |
| `update`    | Rename a folder                                  |
| `delete`    | Delete the folders from the vault                |

### **list**

List all folders associated with the application

`ksm folder list`

* optional parameters:
* `--json` return results in JSON format
* `-f, --folder <folder UID>` List only folders/records in the selected folder UID.
* `-r, --recursive` list recursively all folders/records in the selected folder UID including all subfolders.
* `-l, --list-records` Include folder records info in the output.

{% hint style="info" %}
Without any parameters the command will list all folders shared to the KSM App and if `--list-records` option is present it will also show all records including any records directly shared to the KSM App *(not in a folder)*.
{% endhint %}

**Example 1:** Tabular format

```
$ ksm folder list

 Type Parent                  UID                     Title
 ---- ----------------------- ----------------------- ---------------
 dir                          vZdNYOi7Oh1q6pvI9jY8KA  Applications
 dir                          EVvnsKbrlYHMi4HVTBn3-w  Databases
 dir  EVvnsKbrlYHMi4HVTBn3-w  Bj9bNJjSFobG-VE7MImaIA  Oracle
```

**Example 2:** JSON format

```
$ ksm folder list --json
[
    {
        "type": "dir",
        "parent_uid": "",
        "uid": "vZdNYOi7Oh1q6pvI9jY8KA",
        "title": "Applications"
    },
    {
        "type": "dir",
        "parent_uid": "",
        "uid": "EVvnsKbrlYHMi4HVTBn3-w",
        "title": "Databases"
    },
    {
        "type": "dir",
        "parent_uid": "EVvnsKbrlYHMi4HVTBn3-w",
        "uid": "Bj9bNJjSFobG-VE7MImaIA",
        "title": "Oracle"
    }
]
```

### add

Create a new subfolder into the specified parent folder. KSM can create subfolders only in existing shared folders that are shared to the KSM App including their subfolders and cannot create new shared folder(s).

{% hint style="info" %}
The output of a successful folder creation is the folder UID via standard out. There may be additional text, which is in standard error.&#x20;
{% endhint %}

`ksm folder add --parent-folder <FOLDER UID> --title <FOLDER TITLE>`

Required parameters:

`--parent-folder, -f` The parent folder UID where the new (sub)folder will be created.

`--title, -t` Title of the new folder.

**Example:**

```
ksm folder add --parent-folder vZdNYOi7Oh1q6pvI9jY8KA --title NewApp

The following is the new folder UID ...
Ai9iFYWf6EOE0T9fVAynBg
```

### **update**

Rename a folder.

`ksm folder update --folder <FOLDER UID> --title NEW_TITLE`

Parameters:

* `--folder, -f` - Folder UID of the folder to rename.
* `--title, -t` - The new folder title.

**Example:**

```
$ ksm folder update --folder Ai9iFYWf6EOE0T9fVAynBg --title NewAppTitle
```

### **delete**

Delete a folder in the vault *(shared to the KSM App)*

`ksm folder delete <FOLDER UID>`

Parameters:

* `<FOLDER UID>` UID of the folder to delete (Required)
* `-f, --force` force deletion of non-empty folders (Optional)

**Example:**

```shell
$ ksm folder delete Ai9iFYWf6EOE0T9fVAynBg

UID                     Response Code Error
----------------------- ------------- -----
Ai9iFYWf6EOE0T9fVAynBg  ok
```