# Microsoft OneDrive CLI OneDrive files, folders, metadata, trash, and sharing permissions through Microsoft Graph. ## Install ```bash cmdhub get msdrive ``` ## Authentication OAuth2 ## Agent-Readable Catalog - Machine-readable command catalog: `/cli/msdrive/catalog.json` - Stable command anchors use the `cmd-...` IDs listed under each command. - Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support. ## Overview ```bash 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 ``` ## CLI Overview Microsoft OneDrive adapter CLI Work with Microsoft OneDrive files, folders, and permissions. The intended workflow is: - list or search first - follow up with a short ref such as f1, d1, or r1, or pipe jsonl into the next command - use resolve when you need to inspect what a short ref expands to Use --jsonl for self-pipe flows such as: msdrive file search --query status --jsonl | msdrive file get msdrive folder list --query eval --jsonl | msdrive file list ## Generated Coverage - Command groups: `13` - Total documented command nodes: `41` - Live examples: `4` - Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `resolve`, `version` - Machine-readable output: `--json`, `--jsonl` - Human views: `summary`, `full` ## Auth Contract - Auth mode: OAuth2 - Provider permission model: Microsoft OAuth - Auth scopes: `offline_access`, `User.Read`, `Files.ReadWrite` - Scope note: Used for OneDrive files, folders, and permissions. - Standard commands: `auth login`, `auth logout`, `auth refresh`, `auth status`, `auth whoami` - `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`. - `auth whoami --json` is the stable way to answer identity questions. ## Agent Safety Notes - Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first. - Treat commands marked as mutating as state-changing local or provider operations. - Mutating command paths: `msdrive auth login`, `msdrive auth logout`, `msdrive auth refresh`, `msdrive file delete`, `msdrive file trash`, `msdrive file untrash`, `msdrive file update`, `msdrive file upload`, `msdrive folder create`, `msdrive login`, `msdrive logout`, `msdrive permission add`, `msdrive permission remove`, `msdrive profile create`, `msdrive profile delete`, `msdrive profile use` - No generated `--dry-run` flag was detected for this CLI. Use discovery commands before mutating commands. ## Global Flags - `--json` (bool): Emit JSON machine output - `--jsonl` (bool): Emit JSONL records for piping - `--output` (string): Compatibility output mode: json|jsonl. Prefer --json or --jsonl - `--view` (string): View mode: summary|full Default: `summary`. - `--profile` (string): Config/auth profile Default: `default`. - `--config` (string): Config path override - `--quiet` (bool): Suppress non-essential diagnostics - `--debug` (bool): Enable debug diagnostics - `--limit` (int): Maximum items to emit Default: `50`. - `--page-size` (int): Requested upstream page size Default: `50`. - `--cursor` (string): Continuation cursor - `--no-paginate` (bool): Fetch only one page - `--version` (bool): Print version information ## Command Reference ### `msdrive auth` - Anchor: `cmd-msdrive-auth` - Mutates state: `no` - Supports dry run: `no` Manage Microsoft OneDrive authentication #### `msdrive auth login` - Anchor: `cmd-msdrive-auth-login` - Mutates state: `yes` - Supports dry run: `no` Authenticate with Microsoft OneDrive Example: ```bash msdrive auth login msdrive auth login --help msdrive auth status ``` #### `msdrive auth logout` - Anchor: `cmd-msdrive-auth-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored credentials Example: ```bash msdrive auth login msdrive auth logout msdrive auth logout --help ``` #### `msdrive auth refresh` - Anchor: `cmd-msdrive-auth-refresh` - Mutates state: `yes` - Supports dry run: `no` Refresh stored token Example: ```bash msdrive auth refresh msdrive auth refresh --help ``` #### `msdrive auth status` - Anchor: `cmd-msdrive-auth-status` - Mutates state: `no` - Supports dry run: `no` Show auth status Example: ```bash msdrive auth status msdrive auth status --help ``` #### `msdrive auth whoami` - Anchor: `cmd-msdrive-auth-whoami` - Mutates state: `no` - Supports dry run: `no` Show current OneDrive identity Example: ```bash msdrive auth whoami msdrive auth whoami --help ``` ### `msdrive capabilities` - Anchor: `cmd-msdrive-capabilities` - Mutates state: `no` - Supports dry run: `no` Describe capabilities Example: ```bash msdrive capabilities --help ``` ### `msdrive config` - Anchor: `cmd-msdrive-config` - Mutates state: `no` - Supports dry run: `no` Inspect local configuration #### `msdrive config explain` - Anchor: `cmd-msdrive-config-explain` - Mutates state: `no` - Supports dry run: `no` Explain resolved configuration Example: ```bash msdrive config explain --help ``` ### `msdrive doctor` - Anchor: `cmd-msdrive-doctor` - Mutates state: `no` - Supports dry run: `no` Run msdrive diagnostics Example: ```bash msdrive doctor --help ``` ### `msdrive file` - Anchor: `cmd-msdrive-file` - Mutates state: `no` - Supports dry run: `no` Manage OneDrive files #### `msdrive file delete` - Anchor: `cmd-msdrive-file-delete` - Mutates state: `yes` - Supports dry run: `no` Permanently delete a file Example: ```bash msdrive file delete --all --yes f1 f2 msdrive file delete --help msdrive file delete f1 --yes msdrive file trash f1 ``` Flags: - `--all` (bool): Confirm batch permanent deletion - `--file` (string): File selector - `--yes` (bool): Confirm permanent deletion #### `msdrive file download` - Anchor: `cmd-msdrive-file-download` - Mutates state: `no` - Supports dry run: `no` Download file bytes Example: ```bash msdrive file download msdrive file download --file f1 msdrive file download f1 --out ./notes.txt ``` Flags: - `--file` (string): File selector - `--out` (string): Output path. Omit to print content. #### `msdrive file export` - Anchor: `cmd-msdrive-file-export` - Mutates state: `no` - Supports dry run: `no` Export a Microsoft Office file Example: ```bash msdrive file export msdrive file export f1 --mime-type pdf --out ./file.pdf msdrive file export f1 --out ./file.pdf ``` Flags: - `--file` (string): File selector - `--mime-type` (string): Export format or MIME type Default: `pdf`. - `--out` (string): Output path. Omit to print content. #### `msdrive file get` - Anchor: `cmd-msdrive-file-get` - Mutates state: `no` - Supports dry run: `no` Get file metadata Example: ```bash msdrive file get msdrive file get f1 msdrive file get f1 f2 msdrive file search --query notes --limit 1 --jsonl | msdrive file get ``` Flags: - `--file` (string): File selector #### `msdrive file list` - Anchor: `cmd-msdrive-file-list` - Mutates state: `no` - Supports dry run: `no` List files Example: ```bash 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 ``` Flags: - `--folder` (string): Folder selector - `--query` (string): Name/full-text query - `--trashed` (bool): Include trashed files #### `msdrive file search` - Anchor: `cmd-msdrive-file-search` - Mutates state: `no` - Supports dry run: `no` Search files by name or text Example: ```bash msdrive file search msdrive file search --folder d1 --query notes msdrive file search --query invoice msdrive file search --query notes --trashed ``` Flags: - `--folder` (string): Folder selector - `--query` (string): Name/full-text query - `--trashed` (bool): Include trashed files #### `msdrive file trash` - Anchor: `cmd-msdrive-file-trash` - Mutates state: `yes` - Supports dry run: `no` Move a file to trash Example: ```bash msdrive file search --query notes --jsonl | msdrive file trash --all msdrive file trash --all f1 f2 msdrive file trash --help msdrive file trash f1 ``` Flags: - `--all` (bool): Confirm batch trash - `--file` (string): File selector #### `msdrive file untrash` - Anchor: `cmd-msdrive-file-untrash` - Mutates state: `yes` - Supports dry run: `no` Restore a file from trash Example: ```bash 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 ``` Flags: - `--all` (bool): Confirm batch untrash - `--file` (string): File selector #### `msdrive file update` - Anchor: `cmd-msdrive-file-update` - Mutates state: `yes` - Supports dry run: `no` Update file metadata or parents Example: ```bash 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 ``` Flags: - `--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 upload` - Anchor: `cmd-msdrive-file-upload` - Mutates state: `yes` - Supports dry run: `no` Upload a local file Example: ```bash 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 ``` Flags: - `--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 folder` - Anchor: `cmd-msdrive-folder` - Mutates state: `no` - Supports dry run: `no` Manage OneDrive folders #### `msdrive folder create` - Anchor: `cmd-msdrive-folder-create` - Mutates state: `yes` - Supports dry run: `no` Create a folder Example: ```bash msdrive folder create --help msdrive folder create --name "Project docs" msdrive folder create --parent d1 --name "Notes" ``` Flags: - `--description` (string): Folder description - `--name` (string): Folder name - `--parent` (string): Parent folder selector #### `msdrive folder get` - Anchor: `cmd-msdrive-folder-get` - Mutates state: `no` - Supports dry run: `no` Get folder metadata Example: ```bash msdrive folder get msdrive folder get d1 msdrive folder get d1 d2 msdrive folder list --limit 1 --jsonl | msdrive folder get ``` #### `msdrive folder list` - Anchor: `cmd-msdrive-folder-list` - Mutates state: `no` - Supports dry run: `no` List folders Example: ```bash msdrive folder list msdrive folder list --limit 10 msdrive folder list --query "Project docs" ``` Flags: - `--query` (string): Folder name query - `--trashed` (bool): Include trashed folders #### `msdrive folder search` - Anchor: `cmd-msdrive-folder-search` - Mutates state: `no` - Supports dry run: `no` Search folders by name Example: ```bash msdrive folder search msdrive folder search --query "Project docs" msdrive folder search --query archive --trashed ``` Flags: - `--query` (string): Folder name query - `--trashed` (bool): Include trashed folders ### `msdrive login` - Anchor: `cmd-msdrive-login` - Mutates state: `yes` - Supports dry run: `no` Authenticate with Microsoft OneDrive Example: ```bash msdrive auth status msdrive login ``` ### `msdrive logout` - Anchor: `cmd-msdrive-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored credentials Example: ```bash msdrive auth login msdrive logout ``` ### `msdrive permission` - Anchor: `cmd-msdrive-permission` - Mutates state: `no` - Supports dry run: `no` Manage OneDrive permissions #### `msdrive permission add` - Anchor: `cmd-msdrive-permission-add` - Mutates state: `yes` - Supports dry run: `no` Add a permission Example: ```bash 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 ``` Flags: - `--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): Permission role: reader|commenter|writer Default: `reader`. - `--type` (string): Permission type: user|group|domain|anyone Default: `anyone`. - `--yes` (bool): Confirm broad anyone/domain sharing #### `msdrive permission list` - Anchor: `cmd-msdrive-permission-list` - Mutates state: `no` - Supports dry run: `no` List file permissions Example: ```bash msdrive file search --query notes --limit 1 --jsonl | msdrive permission list msdrive permission list msdrive permission list --file f1 ``` Flags: - `--file` (string): File selector #### `msdrive permission remove` - Anchor: `cmd-msdrive-permission-remove` - Mutates state: `yes` - Supports dry run: `no` Remove a permission Example: ```bash msdrive permission remove --file f1 --permission r1 msdrive permission remove --file f1 r1 msdrive permission remove --help ``` Flags: - `--all` (bool): Confirm batch permission removal - `--file` (string): File selector - `--permission` (string): Permission selector - `--yes` (bool): Confirm permission removal ### `msdrive profile` - Anchor: `cmd-msdrive-profile` - Mutates state: `no` - Supports dry run: `no` Manage provider profiles #### `msdrive profile create` - Anchor: `cmd-msdrive-profile-create` - Mutates state: `yes` - Supports dry run: `no` Create an unauthenticated provider profile Example: ```bash msdrive profile create --help ``` #### `msdrive profile delete` - Anchor: `cmd-msdrive-profile-delete` - Mutates state: `yes` - Supports dry run: `no` Delete a local provider profile Example: ```bash msdrive profile delete --help ``` #### `msdrive profile list` - Anchor: `cmd-msdrive-profile-list` - Mutates state: `no` - Supports dry run: `no` List provider profiles Example: ```bash msdrive profile list --help ``` #### `msdrive profile rename` - Anchor: `cmd-msdrive-profile-rename` - Mutates state: `no` - Supports dry run: `no` Rename a local provider profile Example: ```bash msdrive profile rename --help ``` #### `msdrive profile use` - Anchor: `cmd-msdrive-profile-use` - Mutates state: `yes` - Supports dry run: `no` Set the default provider profile Example: ```bash msdrive profile use --help ``` ### `msdrive resolve` - Anchor: `cmd-msdrive-resolve` - Mutates state: `no` - Supports dry run: `no` Resolve a marker or short id Example: ```bash msdrive resolve --help ``` ### `msdrive schema` - Anchor: `cmd-msdrive-schema` - Mutates state: `no` - Supports dry run: `no` Emit msdrive schema hints Example: ```bash msdrive schema msdrive schema --help msdrive schema file upload --in --json msdrive schema file.upload --input --json msdrive schema file.upload --out --json ``` Flags: - `--in` (bool): Show input schema - `--input` (bool): Show input schema - `--out` (bool): Show output schema ### `msdrive version` - Anchor: `cmd-msdrive-version` - Mutates state: `no` - Supports dry run: `no` Show msdrive version information Example: ```bash msdrive version --help ``` ## Live Examples ### Auth #### Check current OneDrive identity Returns the active Microsoft OneDrive account. _Example metadata: requires auth; provider state: live._ ```bash msdrive auth whoami ``` ```text 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 Lists recent non-trashed files. _Example metadata: requires auth; provider state: live._ ```bash msdrive file list --limit 5 ``` ```text 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 - Files: msdrive file list --limit 10 ``` #### Search files Searches OneDrive files by text. _Example metadata: requires auth; provider state: live._ ```bash msdrive file search --query eval --limit 5 ``` ```text 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 - Files: msdrive file list --limit 10 ``` ### Folders #### List folders Lists visible folders. _Example metadata: requires auth; provider state: live._ ```bash msdrive folder list --limit 5 ``` ```text 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 - Files: msdrive file list --limit 10 ```