Configuration¶
ycli reads its settings from the environment, or from a .env file in the working directory.
An invalid value fails at startup, naming the variable (exit code 2).
Credentials¶
| Variable | Meaning |
|---|---|
YANDEX_ID_OAUTH_TOKEN |
a Yandex OAuth token with Tracker, Wiki and Forms access (fallback name YCLI__AUTH__OAUTH_TOKEN) |
YANDEX_CLOUD_IAM_TOKEN |
a ready IAM token, in place of the OAuth token; it lives up to 12 hours. Exactly one way to sign in is set: a second one is an error (exit code 2) |
YANDEX_CLOUD_SERVICE_ACCOUNT_KEY_FILE |
the path of a service account's authorized key (yc iam key create --output key.json), in place of a token; ycli exchanges it for IAM tokens and renews them. Needs the service-account extra |
YANDEX_CLOUD_SERVICE_ACCOUNT_KEY |
the same key as its JSON text, for a secret store that hands out values rather than files |
YANDEX_ID_ORGANIZATION_ID |
the Yandex 360 organization id, sent as X-Org-Id (fallback name YCLI__AUTH__ORGANIZATION_ID) |
YANDEX_CLOUD_ORGANIZATION_ID |
a Yandex Cloud organization id, sent as X-Cloud-Org-Id. One organization of either kind is required; with both set, Tracker, Wiki and Forms get the Yandex 360 one |
YCLI_PROFILE |
the name of a saved profile to take the token and the organization from, in place of the variables above; --profile wins over it (see Authenticate) |
YANDEX_OAUTH_CLIENT_ID |
your OAuth app's id, for ycli auth login |
YANDEX_OAUTH_CLIENT_SECRET |
your OAuth app's secret: enables the device flow of ycli auth login |
An exported but empty variable counts as unset. See Authenticate.
DataLens takes an IAM token or a service account's key, not an OAuth token, and a Yandex Cloud organization (sent as x-dl-org-id). Without them ycli auth status lists datalens as not configured, with what to set, and still exits 0; ycli doctor skips it; a ycli datalens command exits 2 with the same text.
Settings¶
Optional settings follow the YCLI__<GROUP>__<SETTING> pattern. An empty one counts as unset too.
| Variable | Default | Meaning |
|---|---|---|
YCLI__HTTP__TIMEOUT_SECONDS |
30 |
per-request timeout, seconds (> 0) |
YCLI__HTTP__RETRIES |
3 |
retries of an idempotent request after a 429 or a 5xx (≥ 0) |
YCLI__HTTP__MAX_ITEMS |
500 |
item cap of a listing command without --limit or --all (> 0) |
YCLI__HTTP__MAX_TOOL_ITEMS |
50 |
item cap of a listing tool of the MCP server without limit or all: its answer is read whole into a model's context (> 0) |
YCLI__HTTP__MAX_PAGES |
1000 |
page cap of one listing: a listing that never ends stops here with a warning (> 0) |
YCLI__HTTP__MAX_TOKEN_LENGTH |
16384 |
the longest next token read: a longer one is refused before it is decoded (> 0) |
YCLI__HTTP__MAX_RETRY_AFTER_SECONDS |
60 |
longest pause a 429 may ask for in Retry-After; a longer one fails at once (> 0) |
YCLI__HTTP__MAX_WAIT_SECONDS |
1380 |
how long --wait polls a long operation (an export, a clone, a bulk change) before it gives up; the operation itself keeps running (> 0) |
YCLI__LOGGING__LEVEL |
WARNING |
DEBUG, INFO, WARNING, ERROR or CRITICAL; -v means INFO (every HTTP request), -vv means DEBUG |
YCLI__LOGGING__FORMAT |
text |
text or json (one object per line); logs always go to stderr |
The settings of the HTTP transport (YCLI__MCP__*) are in
Self-host over HTTP.
Exit codes¶
A failed command exits with a code that says what kind of failure it was, so a script can branch without parsing the message.
| Code | Meaning | When |
|---|---|---|
| 0 | ok | the command succeeded |
| 1 | failure | any other failure: a 4xx the API rejected, an unmapped error, a declined confirmation |
| 2 | usage | a bad command line or an invalid YCLI__… setting |
| 3 | not found | the API answered 404, or the token cannot see the object |
| 4 | auth | 401 or 403, or no credentials |
| 5 | rate limited | the API answered 429 and the retries ran out (the hint shows Retry-After) |
| 6 | transient | a 5xx, a timeout or a lost connection: worth retrying later |
| 7 | changes | nothing failed: with --exit-code, ycli sync found something to push |
| 8 | diverged | a file and its object went apart: the object changed on the server since the file was read, or is gone |
| 9 | stale | a listing cannot go on from its token any more: start it again without the token |