@pnp/cli-microsoft365 6.8.0 → 6.9.0-beta.bb31388

package/docs/docs/cmd/spo/folder/folder-copy.mdx

@@ -0,0 +1,57 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder copy
+
+Copies a folder to another location
+
+## Usage
+
+```sh
+m365 spo folder copy [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the folder is located
+
+`-s, --sourceUrl <sourceUrl>`
+: The server- or site-relative URL of the folder to copy
+
+`-t, --targetUrl <targetUrl>`
+: Server-relative URL where to copy the folder
+
+`--allowSchemaMismatch`
+: Ignores any missing fields in the target document library and copies the folder anyway
+```
+
+<Global />
+
+## Remarks
+
+When you copy a folder with documents that have version history, only the latest document version is copied.
+
+## Examples
+
+Copies folder from a document library located in one site collection to another site collection
+
+```sh
+m365 spo folder copy --webUrl https://contoso.sharepoint.com/sites/test1 --sourceUrl /Shared%20Documents/MyFolder --targetUrl /sites/test2/Shared%20Documents/
+```
+
+Copies folder from a document library to another site in the same site collection
+
+```sh
+m365 spo folder copy --webUrl https://contoso.sharepoint.com/sites/test1 --sourceUrl /Shared%20Documents/MyFolder --targetUrl /sites/test1/HRDocuments/
+```
+
+Copies folder to a document library in another site collection. Allow for schema mismatch
+
+```sh
+m365 spo folder copy --webUrl https://contoso.sharepoint.com/sites/test1 --sourceUrl /Shared%20Documents/MyFolder --targetUrl /sites/test2/Shared%20Documents/ --allowSchemaMismatch
+```
+
+## More information
+
+- Copy items from a SharePoint document library: [https://support.office.com/en-us/article/move-or-copy-items-from-a-sharepoint-document-library-00e2f483-4df3-46be-a861-1f5f0c1a87bc](https://support.office.com/en-us/article/move-or-copy-items-from-a-sharepoint-document-library-00e2f483-4df3-46be-a861-1f5f0c1a87bc)

package/docs/docs/cmd/spo/folder/folder-get.mdx

@@ -0,0 +1,55 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder get
+
+Gets information about the specified folder
+
+## Usage
+
+```sh
+m365 spo folder get [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the folder is located.
+
+`-f, --url [url]`
+: The server- or site-relative URL of the folder to retrieve. Specify either `folderUrl` or `id` but not both.
+
+`-i, --id [id]`
+: The UniqueId (GUID) of the folder to retrieve. Specify either `url` or `id` but not both.
+
+`--withPermissions`
+: Set if you want to return associated roles and permissions of the folder. 
+```
+
+<Global />
+
+## Remarks
+
+If no folder exists at the specified URL, you will get a `Please check the folder URL. Folder might not exist on the specified URL` error.
+
+If root level folder is passed, you will get a `Please ensure the specified folder URL or folder Id does not refer to a root folder. Use \'spo list get\' with withPermissions instead' error.` Please use the command 'spo list get'.
+
+## Examples
+
+Get folder properties for a folder with a specific site-relative URL
+
+```sh
+m365 spo folder get --webUrl https://contoso.sharepoint.com/sites/project-x --url "/Shared Documents"
+```
+
+Get folder properties for a folder with a specific id (UniqueId)
+
+```sh
+m365 spo folder get --webUrl https://contoso.sharepoint.com/sites/project-x --id "b2307a39-e878-458b-bc90-03bc578531d6"
+```
+
+Get folder properties with permissions for a folder with server-relative URL
+
+```sh
+m365 spo folder get --webUrl https://contoso.sharepoint.com/sites/test --url "/sites/test/Shared Documents/Test1" --withPermissions
+```

package/docs/docs/cmd/spo/folder/folder-list.mdx

@@ -0,0 +1,121 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# spo folder list
+
+Returns all folders under the specified parent folder
+
+## Usage
+
+```sh
+m365 spo folder list [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the folders to list are located.
+
+`-p, --parentFolderUrl <parentFolderUrl>`
+: The server- or site-relative URL of the parent folder.
+
+`-f, --fields [fields]`
+: Comma-separated list of fields to retrieve. Will retrieve all fields if not specified and json output is requested.
+
+`--filter [filter]`
+: OData filter to use to query the list of folders with.
+
+`-r, --recursive`
+: Set to retrieve nested folders.
+```
+
+<Global />
+
+## Examples
+
+Gets list of folders under a parent folder with site-relative URL
+
+```sh
+m365 spo folder list --webUrl https://contoso.sharepoint.com/sites/project-x --parentFolderUrl '/Shared Documents'
+```
+
+Gets recursive list of folders under a specific folder on a specific site
+
+```sh
+m365 spo folder list --webUrl https://contoso.sharepoint.com/sites/project-x --parentFolderUrl '/sites/project-x/Shared Documents' --recursive
+```
+
+Return a filtered list of folders and only return the list item ID
+
+```sh
+m365 spo folder list --webUrl https://contoso.sharepoint.com/sites/project-x --parentFolderUrl '/Shared Documents' --fields ListItemAllFields/Id --filter "startswith(Name,'Folder')"
+```
+
+## Response
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```json
+  [  
+    {
+      "Exists": true,
+      "IsWOPIEnabled": false,
+      "ItemCount": 9,
+      "Name": "Folder A",
+      "ProgID": null,
+      "ServerRelativeUrl": "/sites/project-x/Shared Documents/Folder A",
+      "TimeCreated": "2022-04-26T12:30:56Z",
+      "TimeLastModified": "2022-04-26T12:50:14Z",
+      "UniqueId": "20523746-971b-4488-aa6d-b45d645f61c5",
+      "WelcomePage": ""
+    }
+  ]
+  ```
+
+  </TabItem>
+  <TabItem value="Text">
+
+  ```text
+  Name      ServerRelativeUrl
+  --------  ------------------------------------------
+  Folder A  /sites/project-x/Shared Documents/Folder A
+  ```
+
+  </TabItem>
+  <TabItem value="CSV">
+
+  ```csv
+  Name,ServerRelativeUrl
+  Folder A,/sites/project-x/Shared Documents/Folder A
+  ```
+
+  </TabItem>
+  <TabItem value="Markdown">
+
+  ```md
+  # spo folder list --webUrl "https://contoso.sharepoint.com" --parentFolderUrl "/Shared Documents"
+
+  Date: 29/3/2023
+
+  ## Folder A (20523746-971b-4488-aa6d-b45d645f61c5)
+
+  Property | Value
+  ---------|-------
+  Exists | true
+  IsWOPIEnabled | false
+  ItemCount | 9
+  Name | Folder A
+  ProgID | null
+  ServerRelativeUrl | /sites/project-x/Shared Documents/Folder A
+  TimeCreated | 2022-04-26T12:30:56Z
+  TimeLastModified | 2022-04-26T12:50:14Z
+  UniqueId | 20523746-971b-4488-aa6d-b45d645f61c5
+  WelcomePage |
+  ```
+
+  </TabItem>
+</Tabs>
+

package/docs/docs/cmd/spo/folder/folder-move.mdx

@@ -0,0 +1,57 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder move
+
+Moves a folder to another location
+
+## Usage
+
+```sh
+m365 spo folder move [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the folder is located
+
+`-s, --sourceUrl <sourceUrl>`
+: The server- or site-relative URL of the folder to move
+
+`-t, --targetUrl <targetUrl>`
+: Server-relative URL where to move the folder
+
+`--allowSchemaMismatch`
+: Ignores any missing fields in the target destination and moves the folder anyway
+```
+
+<Global />
+
+## Remarks
+
+When you move a folder using the `spo folder move` command, all of the document versions are moved.
+
+## Examples
+
+Move folder to a document library in another site collection
+
+```sh
+m365 spo folder move --webUrl https://contoso.sharepoint.com/sites/test1 --sourceUrl /Shared%20Documents/MyFolder --targetUrl /sites/test2/Shared%20Documents/
+```
+
+Move folder to a document library in the same site collection
+
+```sh
+m365 spo folder move --webUrl https://contoso.sharepoint.com/sites/test1 --sourceUrl /Shared%20Documents/MyFolder --targetUrl /sites/test1/HRDocuments/
+```
+
+Move folder to a document library in another site collection. Allow for schema mismatch
+
+```sh
+m365 spo file move --webUrl https://contoso.sharepoint.com/sites/test1 --sourceUrl /Shared%20Documents/sp1.pdf --targetUrl /sites/test2/Shared%20Documents/ --allowSchemaMismatch
+```
+
+## More information
+
+- Move items from a SharePoint document library: [https://support.office.com/en-us/article/move-or-copy-items-from-a-sharepoint-document-library-00e2f483-4df3-46be-a861-1f5f0c1a87bc](https://support.office.com/en-us/article/move-or-copy-items-from-a-sharepoint-document-library-00e2f483-4df3-46be-a861-1f5f0c1a87bc)

package/docs/docs/cmd/spo/folder/folder-remove.mdx

@@ -0,0 +1,47 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder remove
+
+Deletes the specified folder
+
+## Usage
+
+```sh
+m365 spo folder remove [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the folder to be deleted is located.
+
+`-f, --url <url>`
+: The server- or site-relative URL of the folder to delete.
+
+`--recycle`
+: Recycles the folder instead of actually deleting it.
+
+`--confirm`
+: Don't prompt for confirming deleting the folder.
+```
+
+<Global />
+
+## Remarks
+
+The `spo folder remove` command will remove folder only if it is empty. If the folder contains any files, deleting the folder will fail.
+
+## Examples
+
+Remove a folder with a specific site-relative URL
+
+```sh
+m365 spo folder remove --webUrl https://contoso.sharepoint.com/sites/project-x --url '/Shared Documents/My Folder'
+```
+
+Remove a folder with a specific server relative URL to the site recycle bin
+
+```sh
+m365 spo folder remove --webUrl https://contoso.sharepoint.com/sites/project-x --url '/sites/project-x/Shared Documents/My Folder' --recycle
+```

package/docs/docs/cmd/spo/folder/folder-rename.mdx

@@ -0,0 +1,40 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder rename
+
+Renames a folder
+
+## Usage
+
+```sh
+m365 spo folder rename [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the folder to be renamed is located.
+
+`-f, --url <url>`
+: The server- or site-relative URL of the folder (including the folder).
+
+`-n, --name <name>`
+: New name for the target folder.
+```
+
+<Global />
+
+## Examples
+
+Renames a folder with a specific site-relative URL
+
+```sh
+m365 spo folder rename --webUrl https://contoso.sharepoint.com/sites/project-x --url '/Shared Documents/My Folder 1' --name 'My Folder 2'
+```
+
+Renames a folder with a specific server-relative URL
+
+```sh
+m365 spo folder rename --webUrl https://contoso.sharepoint.com/sites/project-x --url '/sites/project-x/Shared Documents/My Folder 1' --name 'My Folder 2'
+```

package/docs/docs/cmd/spo/folder/folder-retentionlabel-ensure.mdx

@@ -0,0 +1,51 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder retentionlabel ensure
+
+Apply a retention label to a folder
+
+## Usage
+
+```sh
+m365 spo folder retentionlabel ensure [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: URL of the site where the retention label from a file to apply is located
+
+`--folderUrl [folderUrl]`
+: The server- or site-relative URL of the folder that should be labelled. Specify either `folderUrl` or `folderId` but not both.
+
+`i, --folderId [folderId]`
+: The UniqueId (GUID) of the folder that should be labelled. Specify either `folderUrl` or `folderId` but not both.
+
+`--name <name>`
+: Name of the retention label to apply to the folder.
+```
+
+<Global />
+
+## Remarks
+
+You can also use [spo listitem retentionlabel remove](./../../../cmd/spo//listitem/listitem-retentionlabel-remove.mdx) for removing the retention label from a listitem.
+
+## Examples
+
+Applies a retention label to a folder based on the label name and the folderUrl
+
+```sh
+m365 spo folder retentionlabel ensure --webUrl https://contoso.sharepoint.com/sites/project-x --folderUrl '/Shared Documents' --name 'Some label'
+```
+
+Applies a retention label to a folder based on the label name and the folderId
+
+```sh
+m365 spo folder retentionlabel ensure --webUrl https://contoso.sharepoint.com/sites/project-x --folderId '26541f96-017c-4189-a604-599e083533b8'  --name 'Some label'
+```
+
+## Response
+
+The command won't return a response on success.

package/docs/docs/cmd/spo/folder/folder-retentionlabel-remove.mdx

@@ -0,0 +1,47 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder retentionlabel remove
+
+Clears the retention label from a folder
+
+## Usage
+
+```sh
+m365 spo folder retentionlabel remove [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The url of the web.
+
+`--folderUrl [folderUrl]`
+: The server- or site-relative URL of the folder of which the label should be removed. Specify either `folderUrl` or `folderId` but not both.
+
+`-i, --folderId [folderId]`
+: The UniqueId (GUID) of the folder of which the label should be removed. Specify either `folderUrl` or `folderId` but not both.
+
+`--confirm`
+: Don't prompt for confirming to remove the label.
+```
+
+<Global />
+
+## Examples
+
+Removes the retention label from a folder in a given site based on the folder id
+
+```sh
+m365 spo folder retentionlabel remove --webUrl https://contoso.sharepoint.com/sites/project-x --folderId 0cd891ef-afce-4e55-b836-fce03286cccf
+```
+
+Removes the retention label from a folder in a given site based on the folder url
+
+```sh
+m365 spo folder retentionlabel remove --webUrl https://contoso.sharepoint.com/sites/project-x --folderUrl /sites/project-x/Shared Documents/Folder --id 1
+```
+
+## Response
+
+The command won't return a response on success.

package/docs/docs/cmd/spo/folder/folder-roleassignment-add.mdx

@@ -0,0 +1,63 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder roleassignment add
+
+Adds a role assignment from the specified folder.
+
+## Usage
+
+```sh
+m365 spo folder roleassignment add [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the folder is located.
+
+`-f, --folderUrl <folderUrl>`
+: The server- or site-relative URL of the folder.
+
+`--principalId [principalId]`
+: The SharePoint principal id. It may be either an user id or group id for which the role assignment will be addd. Specify either upn, groupName or principalId but not multiple.
+
+`--upn [upn]`
+: The upn/email of the user. Specify either upn, groupName or principalId but not multiple.
+
+`--groupName [groupName]`
+: The Azure AD or SharePoint group name. Specify either upn, groupName or principalId but not multiple.
+
+`--roleDefinitionId [roleDefinitionId]`
+: ID of the role definition. Specify either roleDefinitionId or roleDefinitionName but not both.
+
+`--roleDefinitionName [roleDefinitionName]`
+: The name of the role definition. E.g. 'Contribute', 'Read'. Specify either roleDefinitionId or roleDefinitionName but not both
+```
+
+<Global />
+
+## Examples
+
+Add the role assignment to the specified folder based on the group name and role definition name.
+
+```sh
+m365 spo folder roleassignment add --webUrl "https://contoso.sharepoint.com/sites/contoso-sales" --folderUrl  "/Shared Documents/FolderPermission" --groupName "saleGroup" --roleDefinitionName "Edit"
+```
+
+Add the role assignment to the specified folder based on the principal Id and role definition id
+
+```sh
+m365 spo folder roleassignment add --webUrl "https://contoso.sharepoint.com/sites/contoso-sales" --folderUrl "/Shared Documents/FolderPermission" --principalId 2 --roleDefinitionId 1073741827 
+```
+
+Add the role assignment to the specified folder based on the upn and role definition name
+
+```sh
+m365 spo folder roleassignment add --webUrl "https://contoso.sharepoint.com/sites/contoso-sales" --folderUrl "/Shared Documents/FolderPermission" --upn "test@contoso.onmicrosoft.com" --roleDefinitionName "Edit"
+```
+Add the role assignment to the root folder based on the upn and role definition name
+
+```sh
+m365 spo folder roleassignment add --webUrl "https://contoso.sharepoint.com/sites/contoso-sales" --folderUrl "/Shared Documents" --upn "test@contoso.onmicrosoft.com" --roleDefinitionName "Edit"
+```

package/docs/docs/cmd/spo/folder/folder-roleassignment-remove.mdx

@@ -0,0 +1,61 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder roleassignment remove
+
+Removes a role assignment from the specified folder.
+
+## Usage
+
+```sh
+m365 spo folder roleassignment remove [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the folder is located.
+
+`-f, --folderUrl <folderUrl>`
+: The server- or site-relative URL of the folder.
+
+`--principalId [principalId]`
+: The SharePoint principal id. It may be either an user id or group id for which the role assignment will be removed. Specify either upn, groupName or principalId but not multiple.
+
+`--upn [upn]`
+: The upn/email of the user. Specify either upn, groupName or principalId but not multiple.
+
+`--groupName [groupName]`
+: The Azure AD or SharePoint group name. Specify either upn, groupName or principalId but not multiple.
+
+`--confirm`
+: Don't prompt for confirmation when removing the role assignment.
+```
+
+<Global />
+
+## Examples
+
+Remove roleassignment from folder based on group name
+
+```sh
+m365 spo folder roleassignment remove --webUrl "https://contoso.sharepoint.com/sites/contoso-sales" --folderUrl  "/Shared Documents/FolderPermission" --groupName "saleGroup"
+```
+
+Remove the role assignment from the specified folder based on the principal id.
+
+```sh
+m365 spo folder roleassignment remove --webUrl "https://contoso.sharepoint.com/sites/contoso-sales" --folderUrl "/Shared Documents/FolderPermission" --principalId 2
+```
+
+Remove the role assignment from the specified folder based on the principal id without prompting for removal confirmation.
+
+```sh
+m365 spo folder roleassignment remove --webUrl "https://contoso.sharepoint.com/sites/contoso-sales" --folderUrl "/Shared Documents/FolderPermission" --principalId 2 --confirm
+```
+
+Remove the role assignment from the specified folder based on the upn.
+
+```sh
+m365 spo folder roleassignment remove --webUrl "https://contoso.sharepoint.com/sites/contoso-sales" --folderUrl "/Shared Documents/FolderPermission" --upn "test@contoso.onmicrosoft.com"
+```

package/docs/docs/cmd/spo/folder/folder-roleinheritance-break.mdx

@@ -0,0 +1,49 @@
+import Global from '/docs/cmd/_global.mdx';
+
+# spo folder roleinheritance break
+
+Breaks the role inheritance of a folder.
+
+## Usage
+
+```sh
+m365 spo folder roleinheritance break [options]
+```
+
+## Options
+
+```md defintion-list
+`-u, --webUrl <webUrl>`
+: URL of the site where the folder is located.
+
+`-f, --folderUrl <folderUrl>`
+: The server- or site-relative URL of the folder.
+
+`-c, --clearExistingPermissions`
+: Clear all existing permissions from the folder.
+
+`--confirm`
+: Don't prompt for confirmation to breaking role inheritance of the folder.
+```
+
+<Global />
+
+## Examples
+
+Break the inheritance of a folder with a specified site-relative URL.
+
+```sh
+m365 spo folder roleinheritance break --webUrl "https://contoso.sharepoint.com/sites/project-x" --folderUrl "Shared Documents/TestFolder"
+```
+
+Break the inheritance of a folder with a specified server-relative URL. It will clear the existing permissions of the folder. It will **not** prompt for confirmation before breaking the inheritance.
+
+```sh
+m365 spo folder roleinheritance break --webUrl "https://contoso.sharepoint.com/sites/project-x" --folderUrl "/sites/project-x/Shared Documents/TestFolder" --clearExistingPermissions --confirm
+```
+
+Break the inheritance of the specified root folder for the library with a specified server-relative URL. It will clear the existing permissions of the root folder. It will **not** prompt for confirmation before breaking the inheritance.
+
+```sh
+m365 spo folder roleinheritance break --webUrl "https://contoso.sharepoint.com/sites/project-x" --folderUrl "/sites/project-x/Shared Documents" --clearExistingPermissions --confirm
+```