folder
cmdhub adapter

Microsoft OneDrive CLI
for cmdhub.

OneDrive files, folders, metadata, trash, and sharing permissions through Microsoft Graph.

lock Auth: OAuth2
Quick Install cmdhub get msdrive

data_object Agent Contract

Agents should start with auth/status and discovery commands, inspect schemas before composition, and treat commands marked as mutating as state-changing operations.

Output

Use human output for normal reads, `--json` for scripting or complete structured fields, and `--jsonl` for upstream pipe inputs.

Auth

Microsoft OAuth. Used for OneDrive files, folders, and permissions.

Refs

Prefer list/search, then short refs or piped JSONL. Use `resolve` to inspect cached refs.

Schemas

Use `msdrive schema` and `catalog.json` to inspect fields, flags, examples, and side effects.

Auth scopes

offline_accessUser.ReadFiles.ReadWrite

Optional scope bundles

With msdrive auth login --scope-set shared

Files.ReadWriteFiles.ReadWrite.AllSites.ReadWrite.All

terminal Command Reference

Generated from source. Global flags apply to all commands.

Global Flags

--json bool Emit JSON machine output
--jsonl bool Emit JSONL records for piping
--output, -o string Compatibility output mode: json|jsonl. Prefer --json or --jsonl
--view string = summary View mode: summary|full
--profile string = default Config/auth profile
--config string Config path override
--quiet, -q bool Suppress non-essential diagnostics
--debug bool Enable debug diagnostics
--limit int = 50 Maximum items to emit
--page-size int = 50 Requested upstream page size
--cursor string Continuation cursor
--no-paginate bool Fetch only one page
--version, -v bool Print version information
msdrive activity List OneDrive item activity
#cmd-msdrive-activity discovery safe
$ msdrive activity --help
msdrive activity list List recent item activity
#cmd-msdrive-activity-list discovery safe
--file string File selector
$ msdrive activity list
$ msdrive activity list --file f1
msdrive auth Manage Microsoft OneDrive authentication
#cmd-msdrive-auth discovery safe
Manage Microsoft delegated user OAuth credentials for the selected msdrive profile. Tokens are stored in the shared cmdhub credential backend and all OneDrive actions run as the signed-in Microsoft user. Do not enter a normal Microsoft account password, application password, API key, client secret, Azure CLI login, Graph PowerShell session, browser cookie, or OneDrive desktop sync credential.
$ msdrive auth --help
msdrive auth login Authenticate with Microsoft OneDrive
#cmd-msdrive-auth-login mutates state
Authenticate with Microsoft delegated user OAuth. The default path uses Microsoft device-code OAuth with the embedded public client ID and stores the resulting OAuth refresh/access token in the shared cmdhub credential backend. Use –browser for loopback PKCE when a local browser is available. Do not enter a normal Microsoft account password, application password, API key, client secret, Azure CLI login, Graph PowerShell session, browser cookie, or OneDrive desktop sync credential.
--browser bool Use browser loopback OAuth with PKCE instead of device-code OAuth
--scope-set string = default Microsoft Graph scope set to request: default or shared
$ msdrive auth login
$ msdrive auth login --browser
$ msdrive auth login --help
$ msdrive auth login --scope-set shared
$ msdrive auth status
msdrive auth logout Remove stored credentials
#cmd-msdrive-auth-logout mutates state
Remove the selected profile’s Microsoft delegated user OAuth token from the shared cmdhub credential backend.
$ msdrive auth login
$ msdrive auth logout
$ msdrive auth logout --help
msdrive auth refresh Refresh stored token
#cmd-msdrive-auth-refresh mutates state
Refresh the selected profile’s stored Microsoft delegated user OAuth access token from the shared cmdhub credential backend. If refresh fails or scopes are missing, rerun msdrive auth login.
$ msdrive auth refresh
$ msdrive auth refresh --help
msdrive auth status Show auth status
#cmd-msdrive-auth-status discovery safe
Show whether the selected profile has a stored Microsoft delegated user OAuth token in the shared cmdhub credential backend, whether refresh succeeds, which Graph scopes are granted or missing, and whether OneDrive is reachable.
$ msdrive auth status
$ msdrive auth status --help
msdrive auth whoami Show current OneDrive identity
#cmd-msdrive-auth-whoami discovery safe
Show the Microsoft delegated user OAuth identity for the selected profile using the token from the shared cmdhub credential backend. Use auth status for credential storage, token-refresh, scope, and provider-readiness details.
$ msdrive auth whoami
$ msdrive auth whoami --help
msdrive capabilities Describe capabilities
#cmd-msdrive-capabilities discovery safe
--section string Show one capability section: scopes, schemas, or commands
$ msdrive capabilities --help
msdrive change List OneDrive delta changes
#cmd-msdrive-change discovery safe
$ msdrive change --help
msdrive change list List drive or folder changes
#cmd-msdrive-change-list discovery safe
--drive string Drive selector
--folder string Folder selector
$ msdrive change list
$ msdrive change list --folder d1 --cursor cur1
msdrive config Inspect local configuration
#cmd-msdrive-config discovery safe
$ msdrive config --help
msdrive config explain Explain resolved configuration
#cmd-msdrive-config-explain discovery safe
$ msdrive config explain --help
msdrive doctor Run msdrive diagnostics
#cmd-msdrive-doctor discovery safe
$ msdrive doctor --help
msdrive drive Manage visible Microsoft drives
#cmd-msdrive-drive discovery safe
$ msdrive drive --help
msdrive drive get Get drive metadata
#cmd-msdrive-drive-get discovery safe
--drive string Drive selector
$ msdrive drive get
$ msdrive drive get --drive dr1
$ msdrive drive get dr1
msdrive drive list List visible drives
#cmd-msdrive-drive-list discovery safe
$ msdrive drive list
$ msdrive drive use dr1
msdrive drive quota Show drive quota
#cmd-msdrive-drive-quota discovery safe
--drive string Drive selector
$ msdrive drive quota
$ msdrive drive quota dr1
msdrive drive use Select the default drive for this profile
#cmd-msdrive-drive-use mutates state
--drive string Drive selector
$ msdrive drive list
$ msdrive drive use --help
$ msdrive drive use dr1
msdrive file Manage OneDrive files
#cmd-msdrive-file discovery safe
$ msdrive file --help
msdrive file copy Copy a file
#cmd-msdrive-file-copy discovery safe
--conflict string = fail Conflict behavior: fail, rename, or replace
--file string File selector
--folder string Destination folder selector
--name string Copied file name
$ msdrive file copy --help
$ msdrive file copy f1 --folder d2 --name notes-copy.txt
msdrive file delete Permanently delete a file
#cmd-msdrive-file-delete mutates state dry-run
--all bool Confirm batch permanent deletion
--dry-run bool Preview permanent deletion without deleting
--file string File selector
--yes bool Confirm permanent deletion
$ msdrive file delete --all --yes f1 f2
$ msdrive file delete --help
$ msdrive file delete f1 --yes
$ msdrive file trash f1
msdrive file download Download file bytes
#cmd-msdrive-file-download discovery safe
--file string File selector
--out string Output path. Omit to print content.
$ msdrive file download
$ msdrive file download --file f1
$ msdrive file download f1 --out ./notes.txt
msdrive file export Export a Microsoft Office file
#cmd-msdrive-file-export discovery safe
--file string File selector
--mime-type string = pdf Export format or MIME type
--out string Output path. Omit to print content.
$ msdrive file export
$ msdrive file export f1 --mime-type pdf --out ./file.pdf
$ msdrive file export f1 --out ./file.pdf
msdrive file get Get file metadata
#cmd-msdrive-file-get discovery safe
--file string File selector
$ msdrive file get
$ msdrive file get f1
$ msdrive file get f1 f2
$ msdrive file search --query notes --limit 1 --jsonl | msdrive file get
msdrive file list List files
#cmd-msdrive-file-list discovery safe
--created-after string Filter items created on or after RFC3339 or YYYY-MM-DD
--created-before string Filter items created on or before RFC3339 or YYYY-MM-DD
--drive string Drive selector
--folder string Folder selector
--has-link bool Only show items with sharing links
--modified-after string Filter items modified on or after RFC3339 or YYYY-MM-DD
--modified-before string Filter items modified on or before RFC3339 or YYYY-MM-DD
--owned-by string Filter by owner class: me or other
--query string Name/full-text query
--shared bool Only show shared items
--trashed bool Include trashed files
--type string Filter by type: file, folder, package, image, video, audio, office, or pdf
$ msdrive file list
$ msdrive file list --folder d1
$ msdrive file list --folder d1 --query notes
$ msdrive file list --limit 10
$ msdrive folder list --limit 1 --jsonl | msdrive file list
msdrive file move Move a file to another folder
#cmd-msdrive-file-move discovery safe
--file string File selector
--folder string Destination folder selector
--name string Optional new file name
$ msdrive file move --file f1 --folder d2 --name renamed.txt
$ msdrive file move --help
$ msdrive file move f1 --folder d2
msdrive file preview Create a file preview URL
#cmd-msdrive-file-preview discovery safe
--file string File selector
$ msdrive file preview
$ msdrive file preview --file f1
$ msdrive file preview f1
msdrive file replace Replace file content
#cmd-msdrive-file-replace discovery safe
--file string File selector
--mime-type string Content MIME type
--path string Replacement local file path
$ msdrive file replace --file f1 --path ./notes.txt
$ msdrive file replace --help
$ msdrive file replace f1 --path ./notes.txt
msdrive file trash Move a file to trash
#cmd-msdrive-file-trash mutates state dry-run
--all bool Confirm batch trash
--dry-run bool Preview trash without changing files
--file string File selector
$ msdrive file search --query notes --jsonl | msdrive file trash --all
$ msdrive file trash --all f1 f2
$ msdrive file trash --help
$ msdrive file trash f1
msdrive file untrash Restore a file from trash
#cmd-msdrive-file-untrash mutates state dry-run
--all bool Confirm batch untrash
--dry-run bool Preview restore without changing files
--file string File selector
$ msdrive file search --query notes --trashed --jsonl | msdrive file untrash --all
$ msdrive file untrash --all f1 f2
$ msdrive file untrash --help
$ msdrive file untrash f1
msdrive file update Update file metadata or parents
#cmd-msdrive-file-update mutates state
--add-parent stringSlice = [] Folder selector to add as parent
--description string New description
--file string File selector
--name string New file name
--remove-parent stringSlice = [] Folder selector to remove as parent
--starred bool Set starred
$ msdrive file update --help
$ msdrive file update f1 --add-parent d2
$ msdrive file update f1 --add-parent d2 --remove-parent d1
$ msdrive file update f1 --description "Project notes"
$ msdrive file update f1 --name renamed.txt
msdrive file upload Upload a local file
#cmd-msdrive-file-upload mutates state
--conflict string = rename Conflict behavior: fail, rename, or replace
--description string File description
--folder string Parent folder selector
--mime-type string Content MIME type
--name string OneDrive file name
--path string Local file path
$ msdrive file upload --help
$ msdrive file upload --path ./notes.txt --folder d1 --name notes.txt
$ msdrive folder search --query "Project docs" --jsonl | msdrive file upload --path ./notes.txt
msdrive folder Manage OneDrive folders
#cmd-msdrive-folder discovery safe
$ msdrive folder --help
msdrive folder copy Copy a folder
#cmd-msdrive-folder-copy discovery safe
--conflict string = fail Conflict behavior: fail, rename, or replace
--folder string Folder selector
--name string Copied folder name
--parent string Destination parent folder selector
$ msdrive folder copy --help
$ msdrive folder copy d1 --parent d2 --name "Project copy"
msdrive folder create Create a folder
#cmd-msdrive-folder-create mutates state
--description string Folder description
--name string Folder name
--parent string Parent folder selector
$ msdrive folder create --help
$ msdrive folder create --name "Project docs"
$ msdrive folder create --parent d1 --name "Notes"
msdrive folder delete delete a folder
#cmd-msdrive-folder-delete mutates state dry-run
--all bool Confirm batch operation
--dry-run bool Preview operation without changing folders
--folder string Folder selector
--yes bool Confirm permanent deletion
$ msdrive folder delete --help
$ msdrive folder delete d1
msdrive folder get Get folder metadata
#cmd-msdrive-folder-get discovery safe
$ msdrive folder get
$ msdrive folder get d1
$ msdrive folder get d1 d2
$ msdrive folder list --limit 1 --jsonl | msdrive folder get
msdrive folder list List folders
#cmd-msdrive-folder-list discovery safe
--created-after string Filter items created on or after RFC3339 or YYYY-MM-DD
--created-before string Filter items created on or before RFC3339 or YYYY-MM-DD
--drive string Drive selector
--folder string Parent folder selector
--has-link bool Only show items with sharing links
--modified-after string Filter items modified on or after RFC3339 or YYYY-MM-DD
--modified-before string Filter items modified on or before RFC3339 or YYYY-MM-DD
--owned-by string Filter by owner class: me or other
--query string Folder name query
--shared bool Only show shared items
--trashed bool Include trashed folders
--type string Filter by type: file, folder, package, image, video, audio, office, or pdf
$ msdrive folder list
$ msdrive folder list --limit 10
$ msdrive folder list --query "Project docs"
msdrive folder move Move a folder
#cmd-msdrive-folder-move discovery safe
--folder string Folder selector
--name string Optional new folder name
--parent string Destination parent folder selector
$ msdrive folder move --folder d1 --parent d2 --name Archive
$ msdrive folder move --help
$ msdrive folder move d1 --parent d2
msdrive folder trash trash a folder
#cmd-msdrive-folder-trash mutates state dry-run
--all bool Confirm batch operation
--dry-run bool Preview operation without changing folders
--folder string Folder selector
$ msdrive folder trash --help
$ msdrive folder trash d1
msdrive folder untrash untrash a folder
#cmd-msdrive-folder-untrash mutates state dry-run
--all bool Confirm batch operation
--dry-run bool Preview operation without changing folders
--folder string Folder selector
$ msdrive folder untrash --help
$ msdrive folder untrash d1
msdrive folder update Update folder metadata
#cmd-msdrive-folder-update mutates state
--description string New folder description
--folder string Folder selector
--name string New folder name
$ msdrive folder update --help
$ msdrive folder update d1 --description "Working notes"
$ msdrive folder update d1 --name "Project docs"
msdrive mcp Run the MCP server
#cmd-msdrive-mcp discovery safe

Run a stdio Model Context Protocol server for this adapter.

The server exposes read-only resource commands by default. Mutating commands are listed only when explicitly allowed with –allow and remain gated by the command contract safety class.

--allow stringArray = [] Allow mutating command keys such as gmail.message.archive or gmail.message.label.*
--allow-dangerous bool Allow --allow wildcards to include destructive or sends_external commands
--concurrency int Maximum concurrent MCP subprocesses
--max-output int64 = 0 Maximum stdout/stderr bytes captured per MCP command
--print-config bool Print MCP tool configuration and exit
--timeout duration = 0s Per-command MCP subprocess timeout, for example 45s or 2m
$ mcp
$ mcp --print-config
msdrive permission Manage OneDrive permissions
#cmd-msdrive-permission discovery safe
$ msdrive permission --help
msdrive permission add Add a permission
#cmd-msdrive-permission-add mutates state
--allow-discovery bool Allow public/domain discovery
--domain string Domain for domain permission
--email string Email address for user/group permission
--file string File selector
--role string = reader Permission role: reader|writer
--type string = anyone Permission type: user|group|domain|anyone
--yes bool Confirm broad anyone/domain sharing
$ msdrive permission add --file f1 --type anyone --role reader --yes
$ msdrive permission add --file f1 --type user --email person@example.com --role reader
$ msdrive permission add --help
msdrive permission list List file permissions
#cmd-msdrive-permission-list discovery safe
--file string File selector
$ msdrive file search --query notes --limit 1 --jsonl | msdrive permission list
$ msdrive permission list
$ msdrive permission list --file f1
msdrive permission remove Remove a permission
#cmd-msdrive-permission-remove mutates state dry-run
--all bool Confirm batch permission removal
--dry-run bool Preview permission removal without changing permissions
--file string File selector
--permission string Permission selector
--yes bool Confirm permission removal
$ msdrive permission remove --file f1 --permission r1 --yes
$ msdrive permission remove --file f1 r1 --dry-run
$ msdrive permission remove --help
msdrive profile Manage provider profiles
#cmd-msdrive-profile discovery safe
$ msdrive profile --help
msdrive profile create Create an unauthenticated provider profile
#cmd-msdrive-profile-create mutates state
$ msdrive profile create --help
msdrive profile delete Delete a local provider profile
#cmd-msdrive-profile-delete mutates state
$ msdrive profile delete --help
msdrive profile list List provider profiles
#cmd-msdrive-profile-list discovery safe
$ msdrive profile list --help
msdrive profile rename Rename a local provider profile
#cmd-msdrive-profile-rename discovery safe
$ msdrive profile rename --help
msdrive profile use Set the default provider profile
#cmd-msdrive-profile-use mutates state
$ msdrive profile use --help
msdrive resolve Resolve a marker or short id
#cmd-msdrive-resolve discovery safe
$ msdrive resolve --help
msdrive schema Emit msdrive schema hints
#cmd-msdrive-schema discovery safe
--in bool Show input schema
--input bool Show input schema
--out bool Show output schema
$ msdrive schema
$ msdrive schema --help
$ msdrive schema file upload --in --json
$ msdrive schema file.upload --input --json
$ msdrive schema file.upload --out --json
msdrive upload-session Resume or cancel OneDrive large upload sessions
#cmd-msdrive-upload-session discovery safe
$ msdrive upload-session --help
msdrive upload-session cancel Cancel a large upload session
#cmd-msdrive-upload-session-cancel discovery safe dry-run
--dry-run bool Preview upload session cancellation without canceling it
--session string Upload session selector
--yes bool Confirm upload session cancellation
$ msdrive upload-session cancel --help
$ msdrive upload-session cancel us1 --dry-run
$ msdrive upload-session cancel us1 --yes
msdrive upload-session resume Resume a large upload session
#cmd-msdrive-upload-session-resume discovery safe
--session string Upload session selector
$ msdrive upload-session resume --help
$ msdrive upload-session resume us1
msdrive upload-session status Inspect a resumable upload session
#cmd-msdrive-upload-session-status discovery safe
--session string Upload session selector
$ msdrive upload-session status
$ msdrive upload-session status us1
msdrive version Show msdrive version information
#cmd-msdrive-version discovery safe
$ msdrive version --help
msdrive version download Download version bytes
#cmd-msdrive-version-download discovery safe
--file string File selector
--out string Output path. Omit to print content.
--version string Version selector
$ msdrive version download
$ msdrive version download --file f1 v1 --out ./old.bin
msdrive version get Get a file version
#cmd-msdrive-version-get discovery safe
--file string File selector
--version string Version selector
$ msdrive version get
$ msdrive version get --file f1 v1
msdrive version list List file versions
#cmd-msdrive-version-list discovery safe
--file string File selector
$ msdrive version list
$ msdrive version list --file f1
msdrive version restore Restore a file version
#cmd-msdrive-version-restore discovery safe
--file string File selector
--version string Version selector
--yes bool Confirm version restore
$ msdrive version restore --file f1 v1 --yes
$ msdrive version restore --help

play_circle Live Examples

Output captured from a real workspace. Regenerate with scripts/gen-docs.sh --update.

auth

Check current OneDrive identity
$ msdrive auth whoami
Authenticated as kestrelphilip@outlook.com

Next steps:
- Files:        msdrive file list --limit 10
- Folders:      msdrive folder list --limit 10
- Capabilities: msdrive capabilities

files

List recent files
$ msdrive file list --limit 5
REF  TITLE                                                         WHEN
f1   Documents                                                     Wed 29 Apr 05:31
f2   OneDrive Eval Folder {id}  Wed 29 Apr 05:59
f3   OneDrive Eval Folder {id}  Wed 29 Apr 06:00
f4   OneDrive Eval Folder {id}  Wed 29 Apr 06:50
f5   OneDrive Eval Folder {id}  Wed 29 Apr 07:06

Next steps:
- More:   msdrive file list --cursor https://graph.microsoft.com/v1.0/me/drive/root/children?$select=id%2cname%2cdescription%2csize%2ccreatedDateTime%{id}%2cwebUrl%2c%40microsoft.graph.downloadUrl%2cparentReference%2cfile%2cfolder%2cdeleted%2cshared%2ccreatedBy&$top=5&$skiptoken={id}
- Open:   msdrive file get f1
- Search: msdrive file search --query <text>
- Files:  msdrive file list --limit 10
Search files
$ msdrive file search --query eval --limit 5
REF  TITLE                                                         WHEN
f1   OneDrive Eval Folder {id}  Sun 17 May 14:09
f2   OneDrive Eval Folder {id}  Sun 03 May 08:37
f3   OneDrive Eval Folder {id}  Wed 29 Apr 19:12
f4   OneDrive Eval Folder {id}  Thu 30 Apr 12:00
f5   OneDrive Eval Folder {id}  Thu 30 Apr 12:29

Next steps:
- More:   msdrive file list --cursor https://graph.microsoft.com/v1.0/me/drive/root/search(q='eval')?$select=id%2cname%2cdescription%2csize%2ccreatedDateTime%{id}%2cwebUrl%2c%40microsoft.graph.downloadUrl%2cparentReference%2cfile%2cfolder%2cdeleted%2cshared%2ccreatedBy&$top=5&$skiptoken=Ng
- Open:   msdrive file get f1
- Search: msdrive file search --query <text>
- Files:  msdrive file list --limit 10

folders

List folders
$ msdrive folder list --limit 5
REF  TITLE                                                         WHEN
d1   Documents                                                     Wed 29 Apr 05:31
d2   OneDrive Eval Folder {id}  Wed 29 Apr 05:59
d3   OneDrive Eval Folder {id}  Wed 29 Apr 06:00
d4   OneDrive Eval Folder {id}  Wed 29 Apr 06:50
d5   OneDrive Eval Folder {id}  Wed 29 Apr 07:06

Next steps:
- More:   msdrive folder list --cursor https://graph.microsoft.com/v1.0/me/drive/root/children?$select=id%2cname%2cdescription%2csize%2ccreatedDateTime%{id}%2cwebUrl%2c%40microsoft.graph.downloadUrl%2cparentReference%2cfile%2cfolder%2cdeleted%2cshared%2ccreatedBy&$top=5&$skiptoken={id}
- Open:   msdrive folder get d1
- Search: msdrive folder search --query <text>
- Files:  msdrive file list --limit 10

alt_route Composition Patterns

Bridge your ecosystem with zero middleware.

msdrive auth login

# Search for a file, inspect metadata, then list its sharing permissions
msdrive file search --query "project notes" --limit 1 --jsonl \
  | msdrive file get

msdrive permission list --file f1

# Upload into a folder discovered from a pipe
msdrive folder search --query "Project docs" --limit 1 --jsonl \
  | msdrive file upload --path ./notes.txt --name notes.txt