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
7 changes: 5 additions & 2 deletions .agents/skills/yandex-360/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,9 +113,12 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a

- **Never hardcode the token or org id** — always read them from the environment.
- **Respect the MCP annotations** — write tools declare `readOnlyHint=False`; anything
with `destructiveHint=true` deletes data, so confirm intent before calling it. If the
with `destructiveHint=true` deletes data, so confirm intent before calling it. A tool that
grants access (a role, a permission, an access binding, an embedding) says so in its
description and is marked so that the client asks a person on every call; where nobody can
be asked the call is denied, and the CLI with `--yes` is the way, after the user agreed. If the
session must not write at all, run the server with `ycli mcp start --read-only`.
- **CLI deletes ask first** — a command that deletes data prompts on a terminal and, without
- **CLI deletes and grants ask first** — a command that deletes data or grants access prompts on a terminal and, without
one (an agent's shell), exits 2 unless given `--yes`; confirm intent with the user before
adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes
to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited,
Expand Down
7 changes: 5 additions & 2 deletions .claude/skills/yandex-360/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,9 +115,12 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a

- **Never hardcode the token or org id** — always read them from the environment.
- **Respect the MCP annotations** — write tools declare `readOnlyHint=False`; anything
with `destructiveHint=true` deletes data, so confirm intent before calling it. If the
with `destructiveHint=true` deletes data, so confirm intent before calling it. A tool that
grants access (a role, a permission, an access binding, an embedding) says so in its
description and is marked so that the client asks a person on every call; where nobody can
be asked the call is denied, and the CLI with `--yes` is the way, after the user agreed. If the
session must not write at all, run the server with `ycli mcp start --read-only`.
- **CLI deletes ask first** — a command that deletes data prompts on a terminal and, without
- **CLI deletes and grants ask first** — a command that deletes data or grants access prompts on a terminal and, without
one (an agent's shell), exits 2 unless given `--yes`; confirm intent with the user before
adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes
to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited,
Expand Down
7 changes: 5 additions & 2 deletions .opencode/skills/yandex-360/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,9 +115,12 @@ semantics, a service ycli does not wrap yet), read the official docs directly, a

- **Never hardcode the token or org id** — always read them from the environment.
- **Respect the MCP annotations** — write tools declare `readOnlyHint=False`; anything
with `destructiveHint=true` deletes data, so confirm intent before calling it. If the
with `destructiveHint=true` deletes data, so confirm intent before calling it. A tool that
grants access (a role, a permission, an access binding, an embedding) says so in its
description and is marked so that the client asks a person on every call; where nobody can
be asked the call is denied, and the CLI with `--yes` is the way, after the user agreed. If the
session must not write at all, run the server with `ycli mcp start --read-only`.
- **CLI deletes ask first** — a command that deletes data prompts on a terminal and, without
- **CLI deletes and grants ask first** — a command that deletes data or grants access prompts on a terminal and, without
one (an agent's shell), exits 2 unless given `--yes`; confirm intent with the user before
adding it. `--dry-run` prints the write request instead of sending it, the JSON result pipes
to `jq`, and the exit code says what failed (3 not found, 4 auth, 5 rate limited,
Expand Down
9 changes: 8 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,11 +143,18 @@ program stays a test.
`POST`), the effect is always named: `RPC(name, …, effect=…)` has no default for it. A tool
states its annotations only: the root server derives its tags, the service from the name and
`write` from `readOnlyHint`.
An operation that lets someone at data they could not reach (a role, a permission, a
licence, an embedding) says so beside its effect, `grants_access=True`: from that one mark
the CLI asks before it sends it, as before a delete, and the tool carries
`_meta["anthropic/requiresUserInteraction"]` (`GRANTS_ACCESS`), which a client that honours
it answers by asking a person on every call. No list of such operations exists anywhere.
- **Why:** agents and their hosts decide what to auto-approve from these hints; the MCP default
for an unannotated tool is "destructive".
- **Check:** the contract test (`tests/contract/test_contract.py`, one case per way of reaching an
operation, fail-closed both ways) runs every tool and compares its hints with the strongest
effect of the endpoints it sends; `test_arch3_effect_overrides_are_marked` keeps
effect of the endpoints it sends, and its `GRANTS_ACCESS` mark with whether one of them grants
access, both ways; `test_the_help_of_a_command_says_it_grants_access_where_its_tool_is_marked`
holds the command's help to the same mark; `test_arch3_effect_overrides_are_marked` keeps
`# violation(arch-3): <reason>` above every `effect=`, and every such marker above one;
`test_arch3_write_tools_carry_write_tag` keeps `--read-only` complete over the served tools,
and the ast-grep rule `no-tool-tags` keeps a second statement out. `status_get`, the one
Expand Down
7 changes: 5 additions & 2 deletions docs/en/how-to/script-the-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,14 +71,17 @@ $ ycli tracker issues search 'Queue: DE' --limit 100 --next eyJ2IjoxLCJvZiI6…

A token carries its listing: with `--next`, give nothing but the limit and what the command cannot be called without, and that as it was: an argument that differs from the token's is refused by its name, never passed over. A token of a Tracker issue search by a scroll (`--scroll-type`) works once; any other token works again. It also holds the scroll's own token, so `ycli tracker issues scroll-clear --next TOKEN` releases the scroll before it expires; that token is of no use without your credentials and dies with the scroll. A token goes on only in the organization it was returned in: under another account it is refused, not run. A listing that can no longer go on exits with `9`: start it again without the token. A run that asks more pages than `YCLI__HTTP__MAX_PAGES` stops there and says so the same way, with a token to go on from. A small first `--limit` sets the size of the pages for every piece after it, so take the first piece as large as the ones you mean to go on with.

## Delete without a prompt
## Delete or grant access without a prompt

A command that destroys data asks for confirmation at a terminal. In a script there is no one to ask, so it fails with exit code 2 until you pass `--yes` / `-y`:
A command that destroys data, or that grants access (a role on a form or a page, permissions of a queue, an access binding or an embedding in DataLens), asks for confirmation at a terminal. In a script there is no one to ask, so it fails with exit code 2 until you pass `--yes` / `-y`:

```bash
ycli tracker boards delete 7 --yes
ycli wiki access create 7 --role reader --user-uid 9001 --yes
```

The help of a command that grants access says so. `--dry-run` asks nothing: it sends nothing.

## Preview a write

`--dry-run` sends no write and prints the request instead (method, URL, body, never the token), through the same `-o`, and exits 0. A secret in the body, such as the password of a DataLens connection, is printed as `***`, so the output is safe in a CI log. Give such a value from a file outside the repository, mode 600: in `--body-file`, or as one field with `-F password=@secret.txt`. Typed on a command line it stays in the shell history. Write the file of one field with no line break at its end (`printf %s 'secret' > secret.txt`), or the break goes out with the secret. Reads still run, so a command that reads and then writes shows only its first write.
Expand Down
2 changes: 1 addition & 1 deletion docs/en/how-to/use-in-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ docker run --rm -e YANDEX_ID_OAUTH_TOKEN -e YANDEX_ID_ORGANIZATION_ID \

## Commands that do not wait

- **Deletes need `--yes`.** A command that destroys data asks for confirmation; with no terminal it exits with code 2 instead. Pass `--yes` when the pipeline is meant to delete.
- **Deletes and grants need `--yes`.** A command that destroys data, or that grants access (a role on a form or a page, permissions of a queue or an entity, an access binding, a licence or an embedding in DataLens), asks for confirmation; with no terminal it exits with code 2 instead. Pass `--yes` when the pipeline is meant to do it. The help of a command that grants access says so.
- **Output is JSON.** Without a terminal ycli prints JSON, so `jq` reads it: `ycli tracker issues get TRACKER-1 | jq .key`.
- **Try it first.** `--dry-run` prints the request a write would send and sends nothing.

Expand Down
4 changes: 2 additions & 2 deletions docs/en/reference/cli/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ $ ycli auth status [OPTIONS]
**Options**:

* `-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.
* `-y, --yes`: Do not ask before an operation that deletes data or grants access.
* `--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 Down Expand Up @@ -94,7 +94,7 @@ $ ycli auth profiles [OPTIONS]
**Options**:

* `-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.
* `-y, --yes`: Do not ask before an operation that deletes data or grants access.
* `--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 Down
Loading
Loading