Яндекс Офис

yandex-office

Use this skill directory as <full-path-to-yandex-office> in commands below. Do not cd into the skill directory before running commands. CWD determines ./yandex-data; use full script paths from CWD, or pass --data-dir.

Aliases are the account handles passed to commands. Email is the verified Yandex identity behind an alias. Apps, scopes, and tokens are defined in references/yandex-office-auth-principles.md.

Document Map

• (1-16) Frontmatter (metadata version 2026.05.27)
• (17-25) Opening Model
• (27-39) Document Map
• (41-47) Reference Map
• (49-75) Account-First Workflow
• (77-108) Account And OAuth Helper
• (110-135) OAuth App Selector
• (137-160) Token Handling
• (162-195) Common Workflows
• (197-202) Extension Reference Link
• (204-213) Migration, Versioning, License

Reference Map

• Auth model: references/yandex-office-auth-principles.md
• OAuth screen-code / PKCE flow: references/oauth-screen-code-flow.md
• Config and data shape: references/config-data-and-tests.md
• Service overview: references/yandex-service-reference.md
• Extension reference: references/yandex-office-extension.md

Account-First Workflow

Run first: python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --accounts list

If aliases print, choose only an exact listed alias. If no alias is suitable, pause the business task and set up or import the account through yandex-office under user authorization. If nothing prints, no account alias is configured in this CWD yet; choose the minimum setup path from the user's request.

Then choose the sub-skill:

• Mail: mail/mail.md
• Calendar: calendars/calendar.md
• Telemost: telemost/telemost.md
• Disk: disk/disk.md
• Contacts: contacts/contacts.md
• Directory: directory/directory.md
• Forms: forms/forms.md
• Tracker: tracker/tracker.md

Calendar note: calendar is reserved by Python library so the dir was renamed to calendars.

Run the business command from that sub-skill doc with --account <alias>. No-arg oauth_setup.py is legacy/bootstrap troubleshooting, not the primary onboarding path. The literal alias list is valid; discovery uses plural --accounts list, while literal account use is --account list.

Account And OAuth Helper

• List aliases: python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --accounts list
• Create or update an account handle: python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --account <alias>
• Create or resolve an alias from email: python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --email <email>
• Save email under a chosen alias: python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --email <email> --account <alias>
• Start screen-code OAuth: python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --account <alias> --app <app_id> --code-flow start
• Complete screen-code OAuth: python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --account <alias> --code-flow complete --code <confirmation-code>

Do not use --account <alias> to test whether an alias exists. It creates or updates the local account handle. Use it only when that is intended, or after --accounts list already proved the alias exists.

--account <alias> prints compact JSON with alias, optional email, and apps. apps maps each stored token client_id to a configured app ID such as mail-readonly or office-core. Custom client IDs print as custom(scope1, scope2, ...).

--email <email> first reuses an existing alias whose token file already has that email. If none exists, it derives a new alias from the email. Use --email <email> --account <alias> only when the local alias must be explicit.

Maintenance:

• --accounts delete --account <alias> deletes one account token file.
• --accounts reset deletes all account token files. It is destructive; use only after an explicit user request.

OAuth App Selector

Use the default/read app unless the user requests a write-capable operation or explicitly approves broader access.

• Mail read/fetch: default mail-readonly; IMAP mutation/delete: mail-readwrite; SMTP send: mail-smtp.
• Disk read/download: default disk-read; write-capable disk-full.
• Calendar: calendar-user; default app already has operational coverage.
• Contacts: contacts-default; default app already has operational coverage.
• Telemost meetings: telemost-default; default app already has operational coverage.
• Tracker read/search: default tracker-read; write-capable tracker-full.
• Forms export/read: default forms-read; write-capable forms-full.
• Directory lookup/read: default directory-read; write-capable directory-full.

Whole package means office-core: Mail read, Disk full, Calendar, and Telemost. It does not cover Contacts, Tracker, Forms, or Directory. For whole-package OAuth, --app office-core is required. Email and account are optional hints and may not match the verified token identity if the human authorizes while logged into a different Yandex account.

Examples: python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --account <alias> --app office-core --code-flow start then python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --account <alias> --code-flow complete --code <confirmation-code>

To ensure an account covers a workflow, run --account <alias> and read apps. For Calendar plus Telemost, acceptable coverage includes office-core, or both calendar-user and telemost-default. Runtime API responses remain final truth.

Token Handling

The user authorizes OAuth tokens. yandex-office verifies and stores them. Never put an access token in visible command arguments, final text, logs, or artifacts. Warnings print to stderr; stdout is the resolved alias or a structured JSON report, depending on the command.

Prefer the Yandex screen-code flow for new OAuth setup. It creates a PKCE authorization URL, stores pending verifier state in {data_dir}/auth/oauth-code-flow.json, exchanges the short confirmation code, and imports the returned bearer token through managed auth without printing it.

python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --account <alias> --app <app_id> --code-flow start
python3 <full-path-to-yandex-office>/scripts/oauth_setup.py --account <alias> --code-flow complete --code <confirmation-code>

Completion prints token-safe JSON with requested_account, saved_account, email, app_id, client_id, apps, and token_path. For several pending links, run one complete command per code; the CLI tries pending entries in issue order and removes only the matched entry. Account routing is unified for all managed imports: existing verified-email account wins, else explicit --account, else derive an alias from verified email. Details live in references/oauth-screen-code-flow.md.

Common Workflows

Mail:

• Check recent mail without persistence: python3 <full-path-to-yandex-office>/mail/scripts/fetch_emails.py --account <alias> --dry-run --num <limit>
• Preview matching mail body without persistence: python3 <full-path-to-yandex-office>/mail/scripts/fetch_emails.py --account <alias> --dry-run --preview-body --sender <sender-or-pattern>
• Fetch one known message: python3 <full-path-to-yandex-office>/mail/scripts/fetch_emails.py --account <alias> --uid <uid>
• Send an email: python3 <full-path-to-yandex-office>/mail/scripts/send_email.py --account <alias> --to <addr> --subject <subj> --body <text>
• Send with CC/BCC/HTML: python3 <full-path-to-yandex-office>/mail/scripts/send_email.py --account <alias> --to <addr> --cc <addr> --bcc <addr> --subject <subj> --body <html> --content-type html --format json
• Backfill from a UID floor without persisting state: use --from-uid <uid>. Exact single-message fetch uses --uid <uid>.
• Current Mail CLI uses --account; do not write legacy --mailbox.

Telemost transcripts:

• Check-only: python3 <full-path-to-yandex-office>/mail/scripts/fetch_emails.py --account <alias> --filter telemost --dry-run
• Actual bounded fetch: python3 <full-path-to-yandex-office>/mail/scripts/fetch_emails.py --account <alias> --filter telemost --num <limit>
• For "today", use --since-date <YYYY-MM-DD>.
• After actual fetch, process via telemost/telemost.md.

Calendar with Telemost:

• Resolve account.
• Check apps for office-core or Calendar plus Telemost coverage.
• Open calendars/calendar.md.

Disk, Tracker, Contacts, Directory, Forms:

• Choose default app for read/search.
• Choose broader/write app only when requested or approved.
• Open the relevant sub-skill doc and pass --account <alias>.

Extension Reference Link

For low-level Yandex API method extension or audit, read references/yandex-office-extension.md. Do not add raw token parameters, raw-token CLIs, auth_call(...) wrappers, parallel auth registries, per-method response handling, or service-specific HTTP subclasses.

Migration, Versioning, License

Yandex Search moved to https://github.com/bizyumov/yandex-search-skill. Yandex Cloud infrastructure guidance lives in the private standalone yandex-cloud skill repository.

yandex-office uses dated skill versions in YYYY.MM.DD format. Keep VERSION, CHANGELOG.md, and skill metadata aligned.

MIT