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
2 changes: 1 addition & 1 deletion .rulesync/rules/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Claude Code **plugin** under `plugins/yandex-360/`. Published on PyPI as `yandex
plugin (skills + instructions) lives in `plugins/yandex-360/`, listed by the repo-root
`.claude-plugin/marketplace.json`.
- **Output:** every CLI command honors a global `--format/-o` flag (`auto` · `json` · `yaml`
· `pretty` · `csv` · `markdown` · `ndjson`); no output surface hardcodes a service UI URL, and a general per-model deeplink
· `pretty` · `csv` · `markdown` · `ndjson` · `name`); no output surface hardcodes a service UI URL, and a general per-model deeplink
mechanism is deferred. Serialization confinement (ARCH-4), single sources of truth (ARCH-5)
and MCP read/write annotation honesty with `ycli mcp start --read-only` (ARCH-3) are
specified and enforced in [`ARCHITECTURE.md`](ARCHITECTURE.md); read them there.
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Claude Code **plugin** under `plugins/yandex-360/`. Published on PyPI as `yandex
plugin (skills + instructions) lives in `plugins/yandex-360/`, listed by the repo-root
`.claude-plugin/marketplace.json`.
- **Output:** every CLI command honors a global `--format/-o` flag (`auto` · `json` · `yaml`
· `pretty` · `csv` · `markdown` · `ndjson`); no output surface hardcodes a service UI URL, and a general per-model deeplink
· `pretty` · `csv` · `markdown` · `ndjson` · `name`); no output surface hardcodes a service UI URL, and a general per-model deeplink
mechanism is deferred. Serialization confinement (ARCH-4), single sources of truth (ARCH-5)
and MCP read/write annotation honesty with `ycli mcp start --read-only` (ARCH-3) are
specified and enforced in [`ARCHITECTURE.md`](ARCHITECTURE.md); read them there.
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Claude Code **plugin** under `plugins/yandex-360/`. Published on PyPI as `yandex
plugin (skills + instructions) lives in `plugins/yandex-360/`, listed by the repo-root
`.claude-plugin/marketplace.json`.
- **Output:** every CLI command honors a global `--format/-o` flag (`auto` · `json` · `yaml`
· `pretty` · `csv` · `markdown` · `ndjson`); no output surface hardcodes a service UI URL, and a general per-model deeplink
· `pretty` · `csv` · `markdown` · `ndjson` · `name`); no output surface hardcodes a service UI URL, and a general per-model deeplink
mechanism is deferred. Serialization confinement (ARCH-4), single sources of truth (ARCH-5)
and MCP read/write annotation honesty with `ycli mcp start --read-only` (ARCH-3) are
specified and enforced in [`ARCHITECTURE.md`](ARCHITECTURE.md); read them there.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Something not working? [If it does not work](https://ycli.savaznatnov.dev/how-to
```bash
ycli tracker issues get TRACKER-1 # a table at a terminal
ycli tracker issues get TRACKER-1 | jq .summary # JSON when piped
ycli -o yaml wiki pages get onboarding # or pick: -o json | yaml | pretty | csv | markdown | ndjson
ycli -o yaml wiki pages get onboarding # or pick: -o json | yaml | pretty | csv | markdown | ndjson | name
ycli tracker boards delete 7 --dry-run # print the request a write would send
ycli tracker boards delete 7 --yes # a delete asks first; --yes answers
ycli api issues/TRACKER-1 --service tracker # an endpoint ycli does not wrap
Expand Down
2 changes: 1 addition & 1 deletion README.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ pipx install 'yandex-cli[mcp]' # или через pipx
```bash
ycli tracker issues get TRACKER-1 # таблица в терминале
ycli tracker issues get TRACKER-1 | jq .summary # JSON при передаче по конвейеру
ycli -o yaml wiki pages get onboarding # или выберите: -o json | yaml | pretty | csv | markdown | ndjson
ycli -o yaml wiki pages get onboarding # или выберите: -o json | yaml | pretty | csv | markdown | ndjson | name
ycli tracker boards delete 7 --dry-run # напечатать запрос, который отправила бы запись
ycli tracker boards delete 7 --yes # удаление сначала спрашивает; --yes отвечает
ycli api issues/TRACKER-1 --service tracker # эндпоинт, который ycli не оборачивает
Expand Down
13 changes: 13 additions & 0 deletions docs/conventions/resources.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,18 @@ lists the field; `tests/tooling/test_api_drift.py` fails on a mark that explains
query parameter has no model to carry the mark: it is listed in `EXPLAINED` with the `IGNORED`
reason.

### The field that names the object

A reply model marks the one field that says which object it is with `Identity()`
(`ycli.yandex.sync.marks`): `key: Annotated[str | None, Identity()]`. It is the field the
resource's read command takes (`issues get` takes a key, `boards get` an id; where a resource
has `get` and `get-by-id`, plain `get` decides), so `ycli … list -o name | xargs -n1 ycli … get`
works. `-o name` prints it, and a command whose result has no such field is refused before
any request. An item of a listing with no identifier of its own stands in `NO_NAME` of
`tests/architecture/test_names.py` with its reason. The models generated from the DataLens
specification are not marked yet: their resources will name the identifier where the
generator reads it.

---

## 2. Lists: `ItemList[X]` is flat, `XResponse` is the envelope
Expand Down Expand Up @@ -584,6 +596,7 @@ the code sees that the departure was chosen, and a search for `violation(` lists
| Acronyms keep their capitals in a CapWords name | `tests/architecture/test_conventions.py::test_an_acronym_keeps_its_capitals_in_a_name` |
| One name on every surface, no synonym, `get` returns one object | `tests/architecture/test_arch1.py`: `test_arch1_cli_path_equals_mcp_name`, `test_arch1_sdk_method_equals_tool_name`, `test_arch1_a_get_returns_one_object` |
| The verb, the parts and their order | review: `/arch-review` against [Naming an operation](#7-naming-an-operation) |
| The item of a listing names itself, and so does what its resource reads, makes or changes | `tests/architecture/test_names.py` (reasons in `NO_NAME`) |
| An `Annotated` alias is defined once | `tests/architecture/test_conventions.py::test_an_annotated_alias_is_defined_once` |
| Every model field carries a description | `tests/architecture/test_conventions.py::test_every_model_field_has_a_description` |
| An alias name means one thing | `tests/architecture/test_conventions.py::test_an_alias_name_means_one_thing` |
Expand Down
17 changes: 16 additions & 1 deletion docs/en/how-to/script-the-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ type: how-to

## Get JSON

At a terminal ycli prints tables; piped, it prints JSON. Force a format with the global `--format` / `-o` (`auto`, `json`, `yaml`, `pretty`, `csv`, `markdown`, `ndjson`), before or after the command:
At a terminal ycli prints tables; piped, it prints JSON. Force a format with the global `--format` / `-o` (`auto`, `json`, `yaml`, `pretty`, `csv`, `markdown`, `ndjson`, `name`), before or after the command:

```bash
ycli tracker issues get TRACKER-1 | jq . # JSON, because the output is piped
Expand Down Expand Up @@ -44,6 +44,21 @@ ycli tracker issues search 'Queue: TEST' -o ndjson | jq -r .key
- `csv` is UTF-8 with no byte order mark, its lines end with a line feed alone, and a cell is the service's text as it came. A spreadsheet reads a cell that starts with `=` as a formula, so open a file of someone else's text with that in mind.
- Where a listing stopped is said on stderr, as with `-o pretty`: stdout holds the rows alone.

## Feed one command to another

`-o name` prints the identifier of each object on a line: what the command that reads it takes.

```bash
ycli tracker issues search 'Queue: TEST' -o name | xargs -n1 ycli tracker issues get
new=$(ycli tracker issues create --queue TEST --summary 'From a script' -o name)
```

- An object that lies inside another one prints its own identifier: `ycli tracker comments list TEST-1 -o name` prints comment ids, and the issue key is yours to add.
- A command whose result has no identifier (a grant of access, a count) is refused before it sends anything, with exit code 2.
- A reply that leaves the identifier of an item out is an error: nothing is printed, so a script never acts on fewer objects than were listed.
- With `--dry-run` the plan comes back in place of the object, and it is printed as JSON.
- DataLens commands do not print names yet.

## Take a long listing in pieces

A listing stops at 500 items unless told otherwise. `--limit N` takes the first N, `--all` takes everything, and `--next` goes on from where a run stopped. `-o json` and `-o yaml` print what the MCP tool and the SDK give: `{items, truncated, next, total}`, so a script takes the token with `jq -r .next`. A table (`-o pretty`) prints the rows, and where it stopped goes to stderr, ready to paste. The line says that the run stopped at its limit, not that more is left: only the next run can tell, and it may give nothing.
Expand Down
6 changes: 3 additions & 3 deletions docs/en/reference/cli/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ $ ycli auth status [OPTIONS]

**Options**:

* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson|name]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-y, --yes`: Do not ask before an operation that deletes data.
* `--dry-run`: Do not send a write: print the request it would send instead. Reads still run, and only the first write of a command is shown. A secret in the body (a password, a token) is printed as ***.
* `--profile NAME`: Use the credentials saved as this profile (YCLI_PROFILE); the environment's and .env's are then not read. `ycli auth profiles` lists them.
Expand Down Expand Up @@ -71,7 +71,7 @@ $ ycli auth login [OPTIONS]
* `--implicit`: Use the browser paste flow even if a client secret is set.
* `-y, --yes`: Write .env without asking to confirm.
* `--device-name TEXT`: Label shown for this device during OAuth approval.
* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson|name]`: Output format (auto = pretty on a TTY, JSON when piped).
* `--dry-run`: Do not send a write: print the request it would send instead. Reads still run, and only the first write of a command is shown. A secret in the body (a password, a token) is printed as ***.
* `--profile NAME`: Use the credentials saved as this profile (YCLI_PROFILE); the environment's and .env's are then not read. `ycli auth profiles` lists them.
* `-F, --field TEXT`: Set any field of the request body: key=value, key[sub]=value for a nested one (JSON-coerced; repeatable). key=@FILE (@- for stdin) gives the file's text as it is; a string that starts with @ goes in JSON quotes ('text="@ivan"'). A flag of the command wins over it. Objects merge; a list replaces the one below it. Give a secret from a file, not typed here: a command line stays in the shell history. Write that file with no line break at its end (printf %s 'secret' > file), or the break goes out with the secret.
Expand All @@ -93,7 +93,7 @@ $ ycli auth profiles [OPTIONS]

**Options**:

* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson|name]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-y, --yes`: Do not ask before an operation that deletes data.
* `--dry-run`: Do not send a write: print the request it would send instead. Reads still run, and only the first write of a command is shown. A secret in the body (a password, a token) is printed as ***.
* `--profile NAME`: Use the credentials saved as this profile (YCLI_PROFILE); the environment's and .env's are then not read. `ycli auth profiles` lists them.
Expand Down
Loading
Loading