Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 11 additions & 12 deletions .gitleaks.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,19 @@ useDefault = true
[allowlist]
paths = ['''pnpm-lock\.yaml''']

# gitleaks' own rules know Google API keys (AIza…) only. Google calls its OAuth tokens opaque, so these prefixes are
# the observed format, not a promised one: ya29. in Apigee's sample access token, 1// in the sample refresh token of
# the web-server OAuth guide.
# Yandex OAuth tokens: Yandex ID's examples start them with y0_ followed by base64url text
# (https://yandex.ru/dev/id/doc/en/tokens/debug-token); the prefix is the observed format, not a promised one.
[[rules]]
id = "google-oauth-access-token"
description = "Google OAuth 2.0 access token"
regex = '''\b(ya29\.[A-Za-z0-9._-]{20,})'''
id = "yandex-oauth-token"
description = "Yandex OAuth token"
regex = '''\b(y[0-9]_[A-Za-z0-9_-]{30,})'''
secretGroup = 1
keywords = ["ya29."]
keywords = ["y0_", "y1_", "y2_", "y3_"]

# The older Yandex token format, 39 characters from AQAAAA; Yandex may no longer issue it.
[[rules]]
id = "google-oauth-refresh-token"
description = "Google OAuth 2.0 refresh token"
regex = '''(?:^|[^A-Za-z0-9/])(1//[A-Za-z0-9_-]{30,})'''
id = "yandex-oauth-token-legacy"
description = "Yandex OAuth token, older format"
regex = '''\b(AQAAAA[A-Za-z0-9_-]{33})\b'''
secretGroup = 1
entropy = 3.5
keywords = ["1//"]
keywords = ["AQAAAA"]
78 changes: 70 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,77 @@
# ydisk

`ydisk` is a WireCat command-line tool, started from
[cli-template](https://github.com/WireCatLabs/cli-template). Its design is in
[docs/dev/DESIGN.md](docs/dev/DESIGN.md).
`ydisk` gives you and your AI agent your Yandex Disk from the command line. It copies the text of the folders you
choose into WireCat's local store, where `search` finds it by words or by meaning, beside your messages and notes. It
also works with the files live: list, download, upload, copy, move, delete to the trash, restore and public links.

## Quick start
It uses Yandex's official [Disk REST API](https://yandex.ru/dev/disk-api/doc/en/). Text is read from PDF, docx,
xlsx, CSV, TSV, plain text and Markdown files; other files are kept by name.

## Install

Node.js 22.16 or a later 22.x, or 24 or later:

```sh
pnpm install
pnpm build
node dist/bin/ydisk.js doctor
npm install -g @wirecat/yandex-disk-cli
ydisk --version
ydisk doctor
```

`doctor` needs no profile. Every command that uses an account starts with one, a name you choose: `ydisk personal config show`.
## Sign in

`ydisk` signs in with a Yandex OAuth token, which you paste once. It is kept in the system keyring, or in a private
file only you can read where no keyring works; never in an argument or the output.

1. Register an app at [oauth.yandex.com/client/new](https://oauth.yandex.com/client/new/), platform "Web services",
redirect URI `https://oauth.yandex.ru/verification_code`, with the access `cloud_api:disk.read`,
`cloud_api:disk.write` and `cloud_api:disk.info` (only `disk.read` and `disk.info` for a read-only token).
2. Open `https://oauth.yandex.ru/authorize?response_type=token&client_id=<your app's ClientID>` and copy the token
([Yandex's guide](https://yandex.ru/dev/id/doc/en/tokens/debug-token)).
3. Sign in, under a profile name you choose:

```sh
ydisk personal session start # paste the token when asked, or pipe it on stdin
ydisk personal session status --check
```

Yandex says a token lasts several months and is extended while it is used
([Yandex ID](https://yandex.ru/dev/id/doc/en/concepts/ya-oauth-intro)); when Yandex stops accepting it, sign in
again.

## Copy folders and search them

```sh
ydisk personal folders add /Documents
ydisk personal sync --json
ydisk personal search "quarterly budget" --json
ydisk personal documents show <id> --json
```

Yandex Disk has no change feed, so each `sync` lists the chosen folders again and reads only the files that changed
since the last one (by MD5). A file moved inside the chosen folders keeps its id (Yandex's `resource_id`), its tags
and its notes; a file deleted on the Disk leaves the copy at the end of the pass. A chosen folder renamed or moved on
the Disk is unavailable, and its copies leave the store, until you add it again under its new path. Choose folders
rather than the whole Disk: each sync lists every one of their subfolders.

## Work with the files live

```sh
ydisk personal files list --folder /Documents
ydisk personal files download /Documents/notes.md # its text
ydisk personal files download /Documents/plan.pdf --output ./plan.pdf
ydisk personal files upload ./notes.md --folder /Documents
ydisk personal files move /Documents/old.pdf --folder /Archive
ydisk personal files delete /Documents/old.pdf # to the Disk's trash; files restore brings it back
ydisk personal files publish /Documents/plan.pdf # a public link: anyone with it can open the file
```

`ydisk personal api list` lists every operation of the Disk API as its own command.

## Permissions

`files.delete` (a delete, and an upload, copy or move with `--replace`) and `files.share` (a public link) ask first
at a terminal. Make any key stricter in the profile's settings, such as `files.delete=deny` for an agent. Downloads
and uploads go to the address Yandex gives, without the token.

More: [usage](docs/usage.md), [commands](docs/commands.md), [settings](docs/configuration.md),
[security](docs/security.md). Design: [docs/dev/DESIGN.md](docs/dev/DESIGN.md).
6 changes: 3 additions & 3 deletions bin/live
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
// bin/live <keyring account> [arguments for scripts/live.sh, such as the test page's link]
//
// Linux only: it reads the keyring with secret-tool and runs scripts/live.sh with bash.
// The token is the keyring entry `service yandex-disk-cli-live account <keyring account>`, stored once with
// secret-tool store --label="ydisk live check" service yandex-disk-cli-live account <keyring account>
// The token is the keyring entry `service ydisk account <keyring account>`, stored once with
// secret-tool store --label="ydisk live check" service ydisk account <keyring account>
// It stays in this process and reaches scripts/live.sh on stdin only: never an argument, the environment or the
// screen. A version whose shipped code already has a record is not checked again.
import { execFileSync, spawnSync } from "node:child_process"
Expand All @@ -21,7 +21,7 @@ const PACKAGE_JSON = join(ROOT, "package.json")
const LIVE_CHECK = join(ROOT, "scripts/live.sh")
const RECORDS = join(ROOT, "docs/dev/live-checks.txt")
const KIT = join(ROOT, "kit")
const KEYRING_SERVICE = "yandex-disk-cli-live"
const KEYRING_SERVICE = "ydisk"

const fail = (message) => {
process.stderr.write(`live: ${message}\n`)
Expand Down
14 changes: 14 additions & 0 deletions changes/feat-source.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
### Added

- **Sign in with a Yandex OAuth token** pasted once: `session start` reads it hidden or from stdin, checks it with
`GET /v1/disk` and keeps it in the system keyring; `session status --check` says whose it is.
- **Chosen Disk folders as searchable text**: `folders add <path>`, `sync`, `status`, `documents list|show|export`,
`search`, `catalog`, tags, notes and memories, cli-core's shared documents commands. Each sync walks the chosen
folders again (the Disk API has no change feed) and reads only files whose MD5 changed; a moved file keeps its id,
tags and notes. Text from PDF, docx, xlsx, CSV, TSV, text and Markdown.
- **The files live**: `files list|show|download|upload|copy|move|create|delete|restore|publish|unpublish`, by Disk
path. `files delete` moves to the trash. `--replace` and `files delete` ask as `files.delete` does, `files publish`
as `files.share` does. Downloads and uploads go to the address Yandex gives, without the token.
- **`api`**: one command per operation of Yandex's Swagger 1.2 description, 20 in all; the three that answer a download or upload link are left out, and a resource's `file`, `preview` and
`sizes` links are taken out of every answer, with `--all` paging where the
API pages; a permanent delete, `overwrite=true` and a public link ask by `files.delete` and `files.share`.
2 changes: 1 addition & 1 deletion contracts/help.snap
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
ydisk — a new WireCat CLI, started from cli-template
ydisk — Yandex Disk for your AI agents: chosen folders as searchable text, and the files live

Usage: ydisk <profile> <command> [options]
Account commands start with your profile, a name you choose; none is ever assumed.
Expand Down
41 changes: 32 additions & 9 deletions contracts/mcp-catalogue.json
Original file line number Diff line number Diff line change
@@ -1,13 +1,36 @@
{
"session status": "read",
"session list": "read",
"api comments-list": "read",
"api comments-create": "write",
"api comments-get": "read",
"api comments-update": "write",
"api comments-delete": "write",
"comments list": "read",
"comments show": "read",
"comments create": "write",
"comments update": "write"
"folders browse": "read",
"files list": "read",
"files show": "read",
"files download": "read",
"files upload": "write",
"files copy": "write",
"files move": "write",
"files create": "write",
"files delete": "write",
"files restore": "write",
"files publish": "write",
"files unpublish": "write",
"api disk-get": "read",
"api resources-list": "read",
"api resources-create": "write",
"api resources-update": "write",
"api resources-delete": "write",
"api resources-copy": "write",
"api resources-files-list": "read",
"api resources-last-uploaded-list": "read",
"api resources-move": "write",
"api resources-public-list": "read",
"api resources-publish": "write",
"api resources-unpublish": "write",
"api resources-upload-url": "write",
"api public-resources-get": "read",
"api public-settings-update": "write",
"api public-resources-save-to-disk": "write",
"api trash-resources-list": "read",
"api trash-resources-delete": "write",
"api trash-resources-restore": "write",
"api operations-get": "read"
}
Loading
Loading