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`); no output surface hardcodes a service UI URL, and a general per-model deeplink
· `pretty` · `csv` · `markdown` · `ndjson`); 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`); no output surface hardcodes a service UI URL, and a general per-model deeplink
· `pretty` · `csv` · `markdown` · `ndjson`); 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
3 changes: 2 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,8 @@ program stays a test.
resolved: no `print` in any spelling — `builtins.print`, `rich.print`, `pprint` — no stdout
`Console`, `typer.echo` without `err=True`, `sys.stdout`/`sys.__stdout__` or `os.write`) and
`test_arch4_serialization_confined_to_output` (AST: `json.dumps`, `yaml.safe_dump`,
`pydantic_core.to_json`, `.model_dump_json()` and their aliases), each with a bite test.
`pydantic_core.to_json`, `csv.writer`, `csv.DictWriter`, `.model_dump_json()` and their
aliases), each with a bite test.
- **Exceptions:** `ARCH4_SERIALIZATION_HOMES` (`log.py` formats stderr log records with
`json.dumps`; the file engine writes a file of a repository in `sync/formats.py` and takes a
fingerprint from a canonical form in `sync/document.py`, neither a result of a command; `core/continuation.py` packs where a listing stopped into the token that goes on from there) and `# violation(arch-4): <reason>` above a line that touches stdout (the eager
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`); no output surface hardcodes a service UI URL, and a general per-model deeplink
· `pretty` · `csv` · `markdown` · `ndjson`); 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
ycli -o yaml wiki pages get onboarding # or pick: -o json | yaml | pretty | csv | markdown | ndjson
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
ycli -o yaml wiki pages get onboarding # или выберите: -o json | yaml | pretty | csv | markdown | ndjson
ycli tracker boards delete 7 --dry-run # напечатать запрос, который отправила бы запись
ycli tracker boards delete 7 --yes # удаление сначала спрашивает; --yes отвечает
ycli api issues/TRACKER-1 --service tracker # эндпоинт, который ycli не оборачивает
Expand Down
18 changes: 17 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`), 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`), before or after the command:

```bash
ycli tracker issues get TRACKER-1 | jq . # JSON, because the output is piped
Expand All @@ -28,6 +28,22 @@ ycli tracker issues search 'Queue: TEST' -o json | jq -r '.items[].key'

`-o json` makes the format explicit; without it a pipe gets JSON anyway.

## Get a table or one item on a line

`-o csv` and `-o markdown` print a table, `-o ndjson` prints one item on a line:

```bash
ycli tracker issues search 'Queue: TEST' -o csv > issues.csv
ycli tracker queues list -o markdown >> report.md
ycli tracker issues search 'Queue: TEST' -o ndjson | jq -r .key
```

- The columns are the fields ycli knows for that kind of object, the same whatever the reply holds. A field the service added since has no column; `-o json` prints it.
- A nested object becomes columns named through a dot (`status.key`); a list stays one cell, as JSON text.
- A command that answers with one object prints a table of one row, or one line.
- `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.

## 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]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson]`: 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]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson]`: 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]`: Output format (auto = pretty on a TTY, JSON when piped).
* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson]`: 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