Documents & filesYandex Disk

Use the Yandex Disk CLI with your AI agent

Choose Disk folders, sync their text to your computer, read documents and work with files on the Disk.

Choose the Disk folders whose text you want to search, keep their copy current, and work with any file on the Disk live. After this page your agent can answer from the folders you chose and change files only where you allow it. It assumes you have signed in.

On this page:

  1. The profile comes first
  2. Choose folders
  3. Sync
  4. What the copy holds
  5. Read a synced document
  6. Work with files live
  7. Output for scripts

The profile comes first

A profile is a name you choose for one account. It is the first word of every command that uses an account:

ydisk personal status

YDISK_PROFILE=personal does the same for one shell session. No profile is ever assumed, not even the only one: a command without one stops with exit code 2 and lists the profiles on this computer.

Choose folders

folders browse lists the Disk one level at a time, live, so you can find a folder by its path:

ydisk personal folders browse
ydisk personal folders browse --folder /Documents
ydisk personal folders add /Documents/Contracts

A chosen folder brings in everything under it, subfolders included. folders list shows the folders you chose, and folders remove takes one out. The next sync drops its documents from the copy.

Choose a few folders that hold documents, not the whole Disk. Yandex Disk does not tell a tool what changed, so each sync lists every chosen folder and its subfolders again. A folder of photos adds listing time and no searchable text.

Sync

ydisk personal sync
ydisk personal status

sync downloads the files that are new or whose content changed since the last sync, and reads their text. A file deleted on the Disk leaves the copy. A file moved inside the chosen folders keeps its tags and notes.

One sync reads up to 200 files (--limit) and lists up to about 10,000 entries, then saves where it stopped. A large folder takes several runs: run sync again until status shows no pending work. A stop loses nothing, and the next sync goes on from where the last one stopped.

Run sync whenever you want the copy to catch up, for example before you ask your agent about recent files. Nothing runs in the background. sync --rescan reads every chosen folder from the start. Run it once, then go on with a plain sync.

A chosen folder that you rename or move on the Disk is no longer found, and its documents leave the copy. Add it again under its new path.

What the copy holds

On the DiskIn the copy
PDF with a text layer, Word .docx, Excel .xlsx, CSV, TSV, plain text, MarkdownThe text, the name, the path, the size and the dates
A scanned PDF or a pictureThe name, the path and the dates. There is no text to read
Any other file, and any file over 50 MBThe name, the path and the dates

status lists each file kept by name only, with the reason. The files themselves stay on the Disk. The copy holds their text. Times are kept and shown in UTC.

Read a synced document

ydisk personal documents list
ydisk personal documents show 1a2b3c --json
ydisk personal documents export 1a2b3c --output ./contract.md

documents show prints the whole text of one document, found by its id from search or documents list. The id above is an example. documents export writes it to a new Markdown file. Tags, notes and memories stay with a document and never reach the Disk. See find a document.

Work with files live

The files commands go to the Disk directly and need no sync. Paths are Disk paths, such as /Documents/plan.pdf.

ydisk personal files list --folder /Documents
ydisk personal files show /Documents/plan.pdf
ydisk personal files download /Documents/plan.pdf --json
ydisk personal files download /Documents/plan.pdf --output ./plan.pdf
ydisk personal files upload ./notes.md --folder /Documents
ydisk personal files copy /Documents/plan.pdf --folder /Archive
ydisk personal files move /Documents/old.pdf --folder /Archive
ydisk personal files create /Projects/2026
ydisk personal files delete /Documents/old.pdf
ydisk personal files restore trash:/old.pdf
ydisk personal files publish /Documents/plan.pdf
ydisk personal files unpublish /Documents/plan.pdf
  • files download without --output answers the file's text, up to 200,000 characters, so an agent can read a file outside the chosen folders without saving it.
  • files delete moves a file to the Disk's trash, and files restore brings it back by its path in the trash.
  • files publish makes a public link that anyone who has it can open. files unpublish closes it.
  • --replace on an upload, a copy or a move overwrites a file already at that path.

At a terminal the tool asks before a delete, an overwrite and a public link. Over MCP there is no one to ask, so set those permissions for an agent. See settings. Add --dry-run to any change to see what it would do without doing it.

Every operation of Yandex's Disk API is a command too: ydisk personal api list lists them, and ydisk personal api show resources-list shows one operation's parameters without calling Yandex.

Output for scripts

Every command except mcp serve takes --json and prints one JSON value on stdout. Errors are JSON on stderr, with a code to branch on, and each kind of failure has its own exit code. The command reference lists them.

Next: find a document, or connect your agent.