import Global from '../../_global.mdx';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# spo file add

Uploads file to the specified folder

## Usage

```sh
m365 spo file add [options]
```

## Options

```md definition-list
`-u, --webUrl <webUrl>`
: The URL of the site where the file should be uploaded to.

`--folder <folder>`
: The server- or site-relative decoded URL to the folder where the file should be uploaded.

`-p, --path <path>`
: Local path to the file to upload.

`-c, --contentType [contentType]`
: Content type name or ID to assign to the file.

`--checkOut [checkOut]`
: If versioning is enabled, this will check out the file first if it exists, upload the file, then check it in again.

`--overwrite [overwrite]`
: Overwrite the file if it already exists in the target folder. Possible values: `true`, `false`. Default is `true`.

`--fileName [fileName]`
: The name of the file in SharePoint after upload. If not specified, the name of the uploaded file will be used.

`--checkInComment [checkInComment]`
: Comment to set when checking the file in.

`--approve [approve]`
: Will automatically approve the uploaded file.

`--approveComment [approveComment]`
: Comment to set when approving the file.

`--publish [publish]`
: Will automatically publish the uploaded file.

`--publishComment [publishComment]`
: Comment to set when publishing the file.
```

<Global />

## Remarks

This command allows using unknown properties. Each property corresponds to the list item field that should be set when uploading the file.

## Permissions

<Tabs>
  <TabItem value="Delegated">

  | Resource   | Permissions    |
  |------------|----------------|
  | SharePoint | AllSites.Write |

  </TabItem>
  <TabItem value="Application">

  | Resource   | Permissions         |
  |------------|---------------------|
  | SharePoint | Sites.ReadWrite.All |

  </TabItem>
</Tabs>

## Examples

Adds the specified file to the specified site in the specified folder.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg'
```

Adds the specified file to the specified site in the specified sub folder.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents/Sub Folder 1' --path 'C:\MS365.jpg'
```

Adds the specified file to the specified site in the specified folder specifying server-relative folder url.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder '/sites/project-x/Shared Documents' --path 'C:\MS365.jpg'
```

Uploads a file to SharePoint with a different name.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --fileName 'MS365-New.jpg'
```

Adds the specified file to the specified site in the specified folder with specified content type.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --contentType 'Picture'
```

Adds the specified file to the specified site in the specified folder, but checks out existing file before the upload.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --checkOut --checkInComment 'check in comment x'
```

Adds the specified file to the specified site in the specified folder and approves it (when list moderation is enabled).

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --approve --approveComment 'approve comment x'
```

Adds the specified file to the specified site in the specified folder and publishes it.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --publish --publishComment 'publish comment x'
```

Adds the specified file to the specified site in the specified folder and changes single text field value of the list item.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --Title "New Title"
```

Adds the specified file to the specified site in the specified folder and changes person/group field and DateTime field values.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --Editor "[{'Key':'i:0#.f|membership|john.smith@contoso.com'}]" --Modified '6/23/2018 10:15 PM'
```

Adds the specified file to the specified site in the specified folder and changes hyperlink or picture field.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --URL 'https://contoso.com, Contoso'
```

Adds the specified file to the specified site in the specified folder and changes taxonomy field.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --Topic "HR services|c17baaeb-67cd-4378-9389-9d97a945c701"
```

Adds the specified file to the specified site in the specified folder and changes taxonomy multi-value field.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --Topic "HR services|c17baaeb-67cd-4378-9389-9d97a945c701;Inclusion ＆ Diversity|66a67671-ed89-44a7-9be4-e80c06b41f35"
```

Adds the specified file to the specified site in the specified folder and changes choice field and multi-choice field.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --ChoiceField1 'Option3' --MultiChoiceField1 'Option2;#Option3'
```

Adds the specified file to the specified site in the specified folder and changes person/group field that allows multi-user selection.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --AllowedUsers "[{'Key':'i:0#.f|membership|john.smith@contoso.com'},{'Key':'i:0#.f|membership|velin.georgiev@contoso.com'}]"
```

Adds the specified file to the specified site in the specified folder and changes yes/no field.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --HasCar true
```

Adds the specified file to the specified site in the specified folder and changes number field and currency field.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --NumberField 100 --CurrencyField 20
```

Adds the specified file to the specified site in the specified folder and changes lookup field and multi-lookup field.

```sh
m365 spo file add --webUrl https://contoso.sharepoint.com/sites/project-x --folder 'Shared Documents' --path 'C:\MS365.jpg' --LookupField 1 --MultiLookupField "2;#;#3;#;#4;#"
```

## Response

<Tabs>
  <TabItem value="JSON">

  ```json
  {
    "CheckInComment": "",
    "CheckOutType": 2,
    "ContentTag": "{56B8E3C8-8E8A-4600-B9E1-A63D27391799},2,5",
    "CustomizedPageStatus": 0,
    "ETag": "\"{56B8E3C8-8E8A-4600-B9E1-A63D27391799},2\"",
    "Exists": true,
    "ExistsAllowThrowForPolicyFailures": true,
    "ExistsWithException": true,
    "IrmEnabled": false,
    "Length": "19555",
    "Level": 1,
    "LinkingUri": "https://contoso.sharepoint.com/sites/Finance/YearlyReports/Yearly%20report.xlsx?d=w56b8e3c88e8a4600b9e1a63d27391799",
    "LinkingUrl": "https://contoso.sharepoint.com/sites/Finance/YearlyReports/Yearly report.xlsx?d=w56b8e3c88e8a4600b9e1a63d27391799",
    "MajorVersion": 1,
    "MinorVersion": 0,
    "Name": "Yearly report.xlsx",
    "ServerRelativeUrl": "/sites/Finance/YearlyReports/Yearly report.xlsx",
    "TimeCreated": "2026-01-07T10:50:38Z",
    "TimeLastModified": "2026-01-07T10:50:38Z",
    "Title": "",
    "UIVersion": 512,
    "UIVersionLabel": "1.0",
    "UniqueId": "56b8e3c8-8e8a-4600-b9e1-a63d27391799"
  }
  ```

  </TabItem>
  <TabItem value="Text">

  ```text
  CheckInComment                   :
  CheckOutType                     : 2
  ContentTag                       : {56B8E3C8-8E8A-4600-B9E1-A63D27391799},2,5
  CustomizedPageStatus             : 0
  ETag                             : "{56B8E3C8-8E8A-4600-B9E1-A63D27391799},2"
  Exists                           : true
  ExistsAllowThrowForPolicyFailures: true
  ExistsWithException              : true
  IrmEnabled                       : false
  Length                           : 19555
  Level                            : 1
  LinkingUri                       : https://contoso.sharepoint.com/sites/Finance/YearlyReports/Yearly%20report.xlsx?d=w56b8e3c88e8a4600b9e1a63d27391799
  LinkingUrl                       : https://contoso.sharepoint.com/sites/Finance/YearlyReports/Yearly report.xlsx?d=w56b8e3c88e8a4600b9e1a63d27391799
  MajorVersion                     : 2
  MinorVersion                     : 0
  Name                             : Yearly report.xlsx
  ServerRelativeUrl                : /sites/Finance/YearlyReports/Yearly report.xlsx
  TimeCreated                      : 2026-01-07T10:50:38Z
  TimeLastModified                 : 2026-01-07T10:50:38Z
  Title                            :
  UIVersion                        : 512
  UIVersionLabel                   : 1.0
  UniqueId                         : 56b8e3c8-8e8a-4600-b9e1-a63d27391799
  ```

  </TabItem>
  <TabItem value="CSV">

  ```csv
  CheckInComment,CheckOutType,ContentTag,CustomizedPageStatus,ETag,Exists,ExistsAllowThrowForPolicyFailures,ExistsWithException,IrmEnabled,Length,Level,LinkingUri,LinkingUrl,MajorVersion,MinorVersion,Name,ServerRelativeUrl,TimeCreated,TimeLastModified,Title,UIVersion,UIVersionLabel,UniqueId
  ,2,"{56B8E3C8-8E8A-4600-B9E1-A63D27391799},2,5",0,"""{56B8E3C8-8E8A-4600-B9E1-A63D27391799},2""",1,1,1,0,19555,1,https://contoso.sharepoint.com/sites/Finance/YearlyReports/Yearly%20report.xlsx?d=w56b8e3c88e8a4600b9e1a63d27391799,https://contoso.sharepoint.com/sites/Finance/YearlyReports/Yearly report.xlsx?d=w56b8e3c88e8a4600b9e1a63d27391799,3,0,Yearly report.xlsx,/sites/Finance/YearlyReports/Yearly report.xlsx,2026-01-07T10:50:38Z,2026-01-07T10:50:38Z,,512,1.0,56b8e3c8-8e8a-4600-b9e1-a63d27391799
  ```

  </TabItem>
  <TabItem value="Markdown">

  ```md
  # spo file add --webUrl "https://contoso.sharepoint.com/sites/Finance" --folder "/YearlyReports" --path "C:\Yearly report.xlsx"

  Date: 07/01/2026

  ## 56b8e3c8-8e8a-4600-b9e1-a63d27391799

  Property | Value
  ---------|-------
  CheckInComment |
  CheckOutType | 2
  ContentTag | {56B8E3C8-8E8A-4600-B9E1-A63D27391799},2,5
  CustomizedPageStatus | 0
  ETag | "{56B8E3C8-8E8A-4600-B9E1-A63D27391799},2"
  Exists | true
  ExistsAllowThrowForPolicyFailures | true
  ExistsWithException | true
  IrmEnabled | false
  Length | 19555
  Level | 1
  LinkingUri | https://contoso.sharepoint.com/sites/Finance/YearlyReports/Yearly%20report.xlsx?d=w56b8e3c88e8a4600b9e1a63d27391799
  LinkingUrl | https://contoso.sharepoint.com/sites/Finance/YearlyReports/Yearly report.xlsx?d=w56b8e3c88e8a4600b9e1a63d27391799
  MajorVersion | 4
  MinorVersion | 0
  Name | Yearly report.xlsx
  ServerRelativeUrl | /sites/Finance/YearlyReports/Yearly report.xlsx
  TimeCreated | 2026-01-07T10:50:38Z
  TimeLastModified | 2026-01-07T10:50:38Z
  Title |
  UIVersion | 512
  UIVersionLabel | 1.0
  UniqueId | 56b8e3c8-8e8a-4600-b9e1-a63d27391799
  ```

  </TabItem>
</Tabs>

## More information

- Update file metadata with REST API using ValidateUpdateListItem method: [https://robertschouten.com/2018/04/30/update-file-metadata-with-rest-api-using-validateupdatelistitem-method/](https://robertschouten.com/2018/04/30/update-file-metadata-with-rest-api-using-validateupdatelistitem-method/)
- List Items System Update options in SharePoint Online: [https://www.linkedin.com/pulse/list-items-system-update-options-sharepoint-online-andrew-koltyakov/](https://www.linkedin.com/pulse/list-items-system-update-options-sharepoint-online-andrew-koltyakov/)
