$ pip install sharepointcli
To allow authentication you first need to register your application. For steps on how to configure the app in the Azure portal, see Register your app
For general use, the spo configure
command is the fastest way to set up SharePoint CLI.
When you enter this command, the CLI prompts you for the following configurations:
- SharePoint domain
- Application (client) ID
- Application (client) secret
The spo configure
command stores the credentials in the credentials file.
You can configure configure multiple credentials for different SharePoint domains.
Example:
$ spo configure
SharePoint domain (e.g. example.sharepoint.com):
Tenant Id: db3fe96d-1b57-4119-a5fd-bd139021158d
Client Id: fa3ecc92-5994-475e-a647-1f81931aac43
Client Secret: ~vaXZkx&836mH56FymE6Gx7j$t&JT.-5em
Visit the following url to give consent:
https://login.microsoftonline.com/db3fe96d-1b57-4119-a5fd-bd139021158d/oauth2/v2.0/authorize?response_type=...
Paste the authenticated url here:
https://login.microsoftonline.com/common/oauth2/nativeclient?code=....
Authentication Flow Completed. Oauth Access Token Stored. You can now use the API.
Authenticated!
The credentials take precedence in the following order:
- Command line options
- Environment variables
- Credentials file
You can use the following command line options to override the default configuration settings.
-
--client_id
Specifies the Client Id.
-
--client_secret
Specifies the Client Secret
-
--tenant_id
Specifies the Tenant Id
Environment variables provide another way to specify credentials, and can be useful for scripting. If you specify an option by using a parameter on the command line, it overrides any value from the environment variables or the configuration file.
The CLI supports the following environment variables:
-
SPO_HOME
Specifies the home directory. The default path is "~/.spo".
-
SPO_CREDENTIALS_FILE
Specifies the location of the file that the CLI to store credentials. The default path is "~/.spo/credentials".
-
SPO_CLIENT_ID
Specifies the Client Id.
-
SPO_CLIENT_SECRET
Specifies the Client Secret
-
SPO_TENANT_ID
Specifies the Tenant Id
The CLI stores sensitive credential information in a file named credentials in a directory named .spo
in your home directory.
For example, the file generated with spo configure
looks similar to the following:
[example.sharepoint.com]
client_id = fa3ecc92-5994-475e-a647-1f81931aac43
client_secret = ~vaXZkx&836mH56FymE6Gx7j$t&JT.-5em
tenant_id = db3fe96d-1b57-4119-a5fd-bd139021158d
Performs the OAuth authentication flow using the console.
$ spo authenticate [domain]
Configures credentials.
$ spo configure [domain]
Copying a local file to SharePoint.
$ spo cp <LocalPath> <SharePointUrl> or cp <SharePointUrl> <LocalPath>
The following cp command copies a single file to a specified site:
$ spo cp test.txt 'https://example.sharepoint.com/sites/example/Shared documents/test.txt'
upload: test.txt to https://example.sharepoint.com/sites/example/Shared documents/test.txt
The following cp command copies a single file from a SharePoint site:
$ spo cp 'https://example.sharepoint.com/sites/example/Shared documents/test.txt' test.txt
download: https://example.sharepoint.com/sites/example/Shared documents/test.txt' to test.txt
Displays commands help.
$ spo help [topic]
Lists files and folders.
$ spo ls [options] <SharePointUrl>
-mtime n File's status was last changed n*24 hours ago. ('+n' more than n, 'n' exactly n, '-n' less than n)
$ spo ls 'https://example.sharepoint.com/sites/example/Shared documents/*.txt'
Creates folder.
$ spo mkdir <SharePointUrl>
Deletes files.
$ spo rm [options] <SharePointUrl>
-mtime n File's status was last changed n*24 hours ago. ('+n' more than n, 'n' exactly n, '-n' less than n)
$ spo rm 'https://example.sharepoint.com/sites/example/Shared documents/*.txt'
Deletes folder.
$ spo rmdir <SharePointUrl>
Prints the version number.
$ spo version
To run the unit tests:
- create the ~/.spo/credentials credentials file
- export your SharePoint test site url as environment variable 'SITE'
$ spo configure
SharePoint domain (e.g. example.sharepoint.com):
Tenant Id: db3fe96d-1b57-4119-a5fd-bd139021158d
Client Id: fa3ecc92-5994-475e-a647-1f81931aac43
Client Secret: ~vaXZkx&836mH56FymE6Gx7j$t&JT.-5em
$ expot SITE='https://example.sharepoint.com/sites/example/Shared documents/test folder'
$ make test
- Sign in to the Azure portal.
- Select Azure Active Directory.
- Under Manage, select App registrations > New registration.
- Enter a display name for the authentication and click the Register button.
- Copy the Application (client) ID and use it as Client Id for the configuration.
- Under Manage, select Authentication > Add a platform.
- Select Web as platform.
- Set Redirect URI to https://login.microsoftonline.com/common/oauth2/nativeclient
- Click on the Configure button to complete the platform configuration.
- Select Certificates & secrets > Client secrets > New client secret.
- Add a description.
- Select an expiration for the secret (e.g. 24 months).
- Click on the Add button.
- Copy the secret's value for use in configuration as Client Secret. The secret value is never displayed again after you leave this page.
$ spo configure
SharePoint domain (e.g. example.sharepoint.com): <-- your SharePoint domain
Tenant Id: db3fe96d-1b57-4119-a5fd-bd139021158d <-- automagical
Client Id: <<-- copy the Application (client) ID
Client Secret: <<-- copy Client Secret
https://login.microsoftonline.com/db3fe96d-1b57-4119-a5fd-bd139021158d/v2.0/authorize?response_type=code&client_id=...
(open the link in your Browser, and authorize the app)
Paste the authenticated url here:
(paste the Browser's URL, i.e. https://login.microsoftonline.com/common/oauth2/nativeclient?code=0...)
Authentication Flow Completed. Oauth Access Token Stored. You can now use the API.
Authenticated!
This project is licensed under the MIT license.