ycli

<!-- mcp-name: io.github.bim-ba/ycli -->
<div align="center">

# ycli

**One Yandex 360 toolkit — four ways to use it.**
Drive **Tracker**, **Wiki**, and **Forms** from a CLI, an MCP server, a Python SDK,
or a Claude Code plugin. Built for AI agents first — pleasant for humans too.

[![CI](https://img.shields.io/github/actions/workflow/status/bim-ba/ycli/ci.yml?branch=main&logo=githubactions&logoColor=white&label=ci)](https://github.com/bim-ba/ycli/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?logo=pytest&logoColor=white)](https://github.com/bim-ba/ycli)
[![PyPI](https://img.shields.io/pypi/v/yandex-cli?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/yandex-cli/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-lightgrey?logo=opensourceinitiative&logoColor=white)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-bim--ba.github.io%2Fycli-blue?logo=materialformkdocs&logoColor=white)](https://bim-ba.github.io/ycli/)
[![DeepWiki](https://img.shields.io/badge/deepwiki-ask%20the%20repo-blue?logo=readthedocs&logoColor=white)](https://deepwiki.com/bim-ba/ycli)

<img src="https://raw.githubusercontent.com/bim-ba/ycli/main/docs/assets/demo.gif" alt="ycli in action" width="760">

</div>

- 🧩 **One SDK, four surfaces** — write logic once, use it as a CLI, an MCP server, a Python
  library, or a Claude Code plugin.
- 🤖 **Agent-native** — the MCP server exposes read **and write** `tracker_*`, `wiki_*`,
  `forms_*` tools, one per SDK/CLI operation, plus a cross-cutting `status` tool (counts in
  [Coverage](#coverage)), with honest annotations (reads are marked read-only; writes
  declare whether they are destructive/idempotent); `ycli mcp start --read-only` serves a
  reads-only view for cautious deployments, and `--toolsets core` serves a curated everyday
  profile when a host limits how many tools it accepts.
- 🛡️ **Trustworthy** — typed pydantic models, the real Yandex API quirks handled for you,
  and a test suite kept at **100% coverage**.
- ⚡ **Zero-friction start** — `uv add yandex-cli`, `ycli auth login`, go.

The full documentation (tutorial, how-to guides, the CLI, MCP and SDK reference) is at
[bim-ba.github.io/ycli](https://bim-ba.github.io/ycli/).

## Install

```bash
uv add yandex-cli            # CLI + Python SDK
uv add 'yandex-cli[mcp]'     # …plus the MCP server (`ycli mcp start`)
```

Run it without installing, or install it as a standalone tool:

```bash
uvx yandex-cli --help                 # one-off, no install
uv tool install yandex-cli            # persistent CLI
uv tool install 'yandex-cli[mcp]'     # …with the MCP server
```

`pip install yandex-cli` works too. The CLI ships as both `yandex-cli` and the short `ycli`.

Using an AI harness (Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, opencode,
Docker)? See [Install in your harness](https://bim-ba.github.io/ycli/how-to/install-in-your-harness/).

The SDK's `ServiceAccountAuth` (IAM tokens minted from a Yandex Cloud service-account key) needs
the `service-account` extra: `uv add 'yandex-cli[service-account]'`.

## Quick start

Pick the surface that fits how you work.

<details open>
<summary><b>CLI</b></summary>

```bash
uv add yandex-cli
ycli --help
ycli tracker issues get TRACKER-1
ycli wiki pages get onboarding
```

**Output formats** — a global `--format` / `-o` picks how results print (the global options work before or after the subcommand: `ycli -o json tracker issues get K` = `ycli tracker issues get K -o json`; a command that declares an option of its own, like `forms answers export --format`, keeps it):

```bash
ycli tracker issues get TRACKER-1            # auto: a pretty table on a TTY…
ycli tracker issues get TRACKER-1 | jq .     # …and raw JSON when piped (agent/script-safe)
ycli -o yaml wiki pages get onboarding       # or: -o json | -o yaml | -o pretty
ycli --jq .summary tracker issues get TRACKER-1   # filter the JSON with jq; a string prints bare
```

`--jq EXPR` runs a [jq](https://jqlang.org) program over the command's JSON result and prints
like `jq -r`: a string comes out raw, anything else as one compact JSON value per line. It
cannot be combined with `-o yaml` / `-o pretty`, and it needs the `jq` Python package (a
dependency; it has no build for Windows on ARM).

**Deleting asks first.** A command that destroys data (every `delete`, `clear`, `abort`…) asks
`DELETE <url> — this deletes data. Continue?` on stderr when you are at a terminal, and exits 1
if you decline. In a script, a pipe or CI there is no one to ask, so it fails with exit 2 until
you pass `--yes` / `-y`: `ycli tracker boards delete 7 --yes`. Reads and ordinary writes never ask.

**Preview a write.** `--dry-run` sends nothing for any write: it prints the request instead
(method, URL, body; never your token), through the same `-o` / `--jq` output, and exits 0.
Reads still run, so a command that reads and then writes shows its first write only:
`ycli tracker boards delete 7 --dry-run`. (The two commands that ask the API itself to validate
a request, `forms filling submit` and `wiki pages move`, call that `--validate-only`.)

**An endpoint ycli has not wrapped.** `ycli api PATH --service tracker|wiki|forms` calls it like
[`gh api`](https://cli.github.com/manual/gh_api) would, with the same auth, retries, output and exit codes:

```bash
ycli api issues/TRACKER-1 --service tracker --jq .summary           # GET (the default method)
ycli api issues/TRACKER-1/comments --service tracker -F text=@note.md   # POST: a field turns it into one
ycli api pages/descendants --service wiki -f slug=docs --paginate   # every page, as one JSON array
```

`PATH` is relative to the service's base URL; a full URL of a service needs no `--service`, and
any other host is refused (your token never goes elsewhere). `-f key=value` is a string, `-F` is
typed (`true`, `null`, numbers, JSON, `@file` for a file's text, `key[sub]=v` to nest, `key[]=v`
for an array); fields of a GET or DELETE go to the query string, otherwise to a JSON body (`--input
FILE` sends a raw body instead). `-H 'Name: value'` adds a header, `-X` sets the method, and
`--dry-run`, `--yes` and `--jq` behave as everywhere. `--paginate` follows Tracker's `Link: rel="next"`
and Wiki's `next_cursor`; Forms pages its listings in more than one way, so pass its paging
parameters with `-f` yourself.
</details>

<details>
<summary><b>MCP server</b> (read/write)</summary>

Run it over stdio (needs the `mcp` extra):

```bash
ycli mcp start               # full read/write tool set (honest annotations)
ycli mcp start --read-only   # reads-only view for cautious deployments
```

Serving every tool costs a large `tools/list` and some hosts cap a request (VS Code allows
128 tools), so pick what the session needs:

| Flag | Serves |
|---|---|
| `--toolsets tracker,wiki` | only those services (`tracker`, `wiki`, `forms`); default `all` |
| `--toolsets core` | a curated everyday profile of about 40 tools (issues, comments, transitions, worklog, wiki pages and search, form reads) |
| `--tools a,b` / `--exclude-tools a,b` | add or hide single tools by name (unknown names fail at start) |
| `--read-only` | no write tools; always wins over the flags above |
| `--tool-search` | lists a search tool and a call proxy instead of the tools; use it with a large set |

`status_get` is always served. The listing omits output schemas and doctest examples (results
still carry `structuredContent`), which cuts `tools/list` from about 1.9 MB to about 0.5 MB for
the full set.

For several users, serve it over HTTP: each MCP client signs its user in through Yandex ID
(OAuth), and every tool call runs with that user's own Yandex token. Setup, including the
Yandex OAuth app and the reverse proxy, is in [Self-host over HTTP](https://bim-ba.github.io/ycli/how-to/self-host-over-http/).

```bash
ycli mcp start --transport http --toolsets core   # needs YCLI__MCP__BASE_URL and an OAuth app
```

List the tool names a given set of flags exposes without running the server:

```bash
ycli mcp methods --toolsets core --read-only
```

Point an MCP client at it — no prior install needed via `uvx` (tools are namespaced
`tracker_*`, `wiki_*`, `forms_*`):

```json
{
  "mcpServers": {
    "yandex": {
      "command": "uvx",
      "args": ["--from", "yandex-cli[mcp]", "ycli", "mcp", "start"],
      "env": {
        "YANDEX_ID_OAUTH_TOKEN": "...",
        "YANDEX_ID_ORGANIZATION_ID": "..."
      }
    }
  }
}
```
</details>

<details>
<summary><b>Python SDK</b></summary>

```python
from ycli.yandex.tracker.client import TrackerClient

tracker = TrackerClient(oauth_token="…", organization_id="…")
issue = tracker.issues.get("TRACKER-1")
print(issue.summary)
```
</details>

<details>
<summary><b>Claude Code plugin</b></summary>

```
/plugin marketplace add bim-ba/ycli
/plugin install yandex-360@ycli
```

Teaches an agent to drive Yandex 360 through `ycli` — including the real API quirks.
See [`plugins/yandex-360/`](plugins/yandex-360/).
</details>

## Skills (Claude Code plugin)

| Skill | Use for |
|-------|---------|
| `yandex-360` | Entry point — install + auth, pick a surface (CLI/MCP/SDK), route to a domain |
| `yandex-360-tracker` | Issues, epics, comments, transitions, links, worklog, changelog |
| `yandex-360-wiki` | Wiki pages, page tree, comments, attachments, YFM authoring |
| `yandex-360-forms` | Forms, questions/schema, responses, publishing |

The skills encode the read/write commands **and** the gnarly Yandex API quirks
(epic-vs-parent, transition discovery, permanent wiki slugs, `fields=` rules, Forms
host/header traps, answers pagination).

## Configure

`ycli` reads two values from the environment (or a `.env` file — `cp .env.example .env`):

```bash
YANDEX_ID_OAUTH_TOKEN=...        # a Yandex OAuth token with Tracker/Wiki/Forms access
YANDEX_ID_ORGANIZATION_ID=...