> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install and use the toloka CLI for shared authentication and project setup, Data Labeling pipelines, and Train workflows.

Use `toloka` to sign in, select a project, move dataset rows, and automate both products. For Data Labeling, it reconciles typed pipeline source and operates pipeline runs. For Train, it creates Training drafts, calculates estimates, controls Training Runs, and downloads Model Versions.

The [pipeline authoring SDK](https://docs.platform.toloka.ai/docs/sdk/pipelines.md) authors Data Labeling pipeline source only. To drive either product directly over HTTP, use the [HTTP API](https://docs.platform.toloka.ai/docs/api-reference.md).

> [!NOTE]
>
> Use the latest CLI release. If a Data Labeling project imports `@toloka-platform/sdk`, use its latest release too. CLI and SDK releases share a version, while installation and updates remain separate; both can change between minor `0.x` releases.

## Shared setup

### Before you start

You need:

* macOS or Linux on ARM64/x64. The installer uses compatible Bun or downloads a standalone executable; native downloads require glibc Linux, `curl`, `tar`, `mktemp`, and SHA-256 tooling. No separate runtime installation is required for the native path. Native Windows packages are not provided.
* A Toloka account on a team. [`toloka login`](https://docs.platform.toloka.ai/docs/cli/reference/login) signs you in through your browser. Only automation that runs without a browser needs an API key; generate one in the Business Console: open your company, switch to **API keys**, and click **Generate API key**. The same tab lists and deletes keys. See [Manage your team and balance](https://docs.platform.toloka.ai/docs/core/teams-and-balance.md#top-up).

### Install

```sh theme={null}
curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
```

With stable Bun 1.4.0 or newer matching the host architecture, the installer uses Bun's global SDK package. Otherwise it installs a checksum-verified standalone executable into `~/.local/bin`, without changing Bun. Add the printed directory to `PATH` if prompted.

Force a mode with `curl -fsSL https://platform.toloka.ai/cli/install.sh | sh -s -- --native` or `--bun`. Forced Bun fails when incompatible; a failed Bun package install never silently switches to native.

The default installer follows `latest`. For SDK development, use Bun as the runtime and package manager and add the SDK to each project that imports it:

```sh theme={null}
bun add @toloka-platform/sdk@latest
```

CLI-only workflows, including Training, do not need that dependency. Projects that import SDK authoring or testing APIs do.

`TOLOKA_CLI_INSTALL_DIR` overrides the native directory and requires `--native` when Bun is present. `TOLOKA_CLI_CHANNEL` selects the release channel; `TOLOKA_CLI_PACKAGE` overrides the selected mode's SDK or native package. `TOLOKA_CLI_REGISTRY` selects the installer registry. Use an explicit mode with custom packages. Automatic updates always use the public npm registry.

#### Updates and migration from Bun global installs

Rerun the installer with its original mode and overrides for an immediate manual update to the latest release:

```sh theme={null}
curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
```

The CLI checks for eligible updates at most daily, after a release is at least 24 hours old. Run [`toloka config set auto-update false`](https://docs.platform.toloka.ai/docs/cli/reference/config/set) to turn that off. `TOLOKA_SKIP_AUTO_UPDATE=1` skips the check for one command, and CI never checks unless `TOLOKA_AUTO_UPDATE=1` is set.

Both installs can coexist. To pick one, put its directory first on `PATH`, refresh the shell cache (`hash -r` in Bash, `rehash` in Zsh), then run [`toloka version --json`](https://docs.platform.toloka.ai/docs/cli/reference/version) to confirm which one answers: the channel is `native` for the standalone executable or `global-registry` for the Bun global package. Credentials, settings, and project dependencies stay unchanged.

### Sign in

```
toloka login
```

Run [`toloka login`](https://docs.platform.toloka.ai/docs/cli/reference/login) and choose browser sign-in. Complete the Google or Microsoft sign-in flow, creating a Toloka account first if needed. The CLI saves the session only after the platform accepts the account. If `TOLOKA_API_KEY` is set, [`login`](https://docs.platform.toloka.ai/docs/cli/reference/login) stores that key without prompting; the flags below also skip the chooser. On success:

```
✔ Logged in to https://platform.toloka.ai as you@example.com
  12 projects visible · session renews automatically until 2026-09-25T10:00:00Z, then run toloka login again
```

The session is created under `$TOLOKA_CLI_CREDENTIALS_DIR` (default `~/.toloka/cli/credentials/`) with mode `0600` in directories with mode `0700`. The platform choice and your project aliases go to `$XDG_CONFIG_HOME/toloka/credentials.json` (default `~/.config/toloka/credentials.json`). If that path has no file, the CLI still reads the older `~/.toloka/credentials.json`.

The session renews itself for up to 14 days after signing in. When it expires, run [`toloka login`](https://docs.platform.toloka.ai/docs/cli/reference/login) again. The first sign-in on a machine also asks you to allow the Toloka CLI once.

[`toloka login --browser`](https://docs.platform.toloka.ai/docs/cli/reference/login) skips the question and goes straight to the browser flow; coding agents and scripts that sign the user in should use it. [`toloka login --no-browser`](https://docs.platform.toloka.ai/docs/cli/reference/login) does the same but prints the link instead of opening a browser.

An API key is the alternative for scripts, CI, and coding agents: it does not expire until you delete it in the Business Console. Choose **Use an API key** in [`toloka login`](https://docs.platform.toloka.ai/docs/cli/reference/login) to type one at a masked prompt, or without a terminal pipe it: [`toloka login --api-key-stdin < key.txt`](https://docs.platform.toloka.ai/docs/cli/reference/login). The key never enters shell history or the process list, which `--api-key <key>` and `TOLOKA_API_KEY` cannot promise. An agent session without a terminal opens the chooser page in your browser on its own.

[`toloka logout`](https://docs.platform.toloka.ai/docs/cli/reference/logout) removes local credentials and attempts to sign out stored browser sessions. Check its output to confirm that sign-out succeeded. It does not revoke an API key; delete the key in the Business Console.

CI does not need [`login`](https://docs.platform.toloka.ai/docs/cli/reference/login) for [`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan), [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply), [`validate`](https://docs.platform.toloka.ai/docs/cli/reference/validate), [`status`](https://docs.platform.toloka.ai/docs/cli/reference/status), [`dataset`](https://docs.platform.toloka.ai/docs/cli/reference/dataset), [`pipeline`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline), and [`secret`](https://docs.platform.toloka.ai/docs/cli/reference/secret) commands. Set `TOLOKA_API_KEY` to override the stored login. The stored platform URL and selected project still apply unless you also set `--base-url` / `TOLOKA_BASE_URL` and `--project-id` / `TOLOKA_PROJECT_ID`. [`project add`](https://docs.platform.toloka.ai/docs/cli/reference/project/add), [`project create`](https://docs.platform.toloka.ai/docs/cli/reference/project/create), [`project switch`](https://docs.platform.toloka.ai/docs/cli/reference/project/switch), and [`project remove`](https://docs.platform.toloka.ai/docs/cli/reference/project/remove) still need the stored login from [`login`](https://docs.platform.toloka.ai/docs/cli/reference/login).

Earlier releases named these variables `POTATO_API_KEY`, `POTATO_BASE_URL`, and `POTATO_PROJECT_ID`. The CLI still reads each legacy name when its `TOLOKA_*` counterpart is unset, prefers the `TOLOKA_*` value when both are set, and prints `POTATO_API_KEY is deprecated and will stop being read; set TOLOKA_API_KEY instead.` (and the same line for the other two) on stderr once per command. The aliases remain supported for compatibility; rename them to silence the warning and use the current names in new automation.

### Verify the connection

Check what the CLI will use. The call needs a login and does not change the project:

```
toloka whoami
```

[`whoami`](https://docs.platform.toloka.ai/docs/cli/reference/auth-status) is an alias of [`auth-status`](https://docs.platform.toloka.ai/docs/cli/reference/auth-status). A working login prints the platform URL, a `Login:` line for the browser session (or a masked API key), the selected project, `Reachable: N project(s) visible.`, and an `Account:` line with your email.

Pass `--show-token` only when you need the full key or access token on this terminal. It prints the value unmasked, so it can land in scrollback, logs, or a screenshot.

Exit code `1` means the CLI could not confirm a working login or encountered a local error. Use the reported message in [Troubleshooting](#troubleshooting).

Then list the projects the key can see:

```
toloka project list
```

Each row is the project id, name, and, for the selected project, its local alias. The selected project is marked `*`; other rows show `-`. An empty account prints `No projects visible.`

### Initialize agent guidance

The [Toloka agent bootstrap](https://platform.toloka.ai/agents/SKILL.md) routes a coding agent to the Data Labeling, fine-tuning, or gisting runbook and its packaged skill.

For a Data Labeling project, create a directory, install the TypeScript SDK, and initialize the agent entry points:

```sh theme={null}
mkdir cat-labeling && cd cat-labeling
bun add @toloka-platform/sdk@latest
toloka init
```

The agent can then author the pipeline source, validate it, show the plan, and apply approved changes. [`project create`](https://docs.platform.toloka.ai/docs/cli/reference/project/create), [`import`](https://docs.platform.toloka.ai/docs/cli/reference/import), or explicit project identity on [`init`](https://docs.platform.toloka.ai/docs/cli/reference/init) writes `toloka.json`; do not edit it by hand.

Train workflows do not need the SDK dependency. Run [`toloka init`](https://docs.platform.toloka.ai/docs/cli/reference/init) in the project's bound checkout to install the bundled agent guidance. In an unbound directory, pass `toloka --project-id <id> init`.

### Select a project

Commands that access project data need a selected project. Highest wins:

1. `--project-id`
2. `TOLOKA_PROJECT_ID`
3. `projectId` in `toloka.json` in the discovered checkout
4. the `current` alias in the credentials file

If none of those resolve, the command fails with `No project selected. Run toloka project create for a new project, toloka project add for an existing project, or cd into a checkout.` or `Missing project ID. Pass --project-id, set TOLOKA_PROJECT_ID, use a bound toloka.json, run toloka project create for a new project, or run toloka project add for an existing project.`

A directory is a checkout when it contains `toloka.json`. Commands walk up from the working directory until they find that file, and print `Using project root <path> (found from <cwd>).` on stderr when that path is not the working directory. `--source-root` disables discovery. [`init`](https://docs.platform.toloka.ai/docs/cli/reference/init) always uses the working directory or `--source-root`; it installs agent entry points without requiring a selected platform project. To bind the directory when running [`init`](https://docs.platform.toloka.ai/docs/cli/reference/init), pass `--project-id`, set `TOLOKA_PROJECT_ID`, or use an existing `toloka.json` binding. Selecting a project with [`project switch`](https://docs.platform.toloka.ai/docs/cli/reference/project/switch) alone does not bind [`init`](https://docs.platform.toloka.ai/docs/cli/reference/init).

Register and import an existing project, then initialize this directory:

```
toloka project add cats pp.019ffa5f-29a7-74de-a76c-7ba5ceedf37f
toloka import pp.019ffa5f-29a7-74de-a76c-7ba5ceedf37f
toloka init
```

[`project add`](https://docs.platform.toloka.ai/docs/cli/reference/project/add) with no arguments prompts for alias and id. The new alias becomes the local alias registry's `current` value. [`import`](https://docs.platform.toloka.ai/docs/cli/reference/import) binds this directory by writing `toloka.json` with the project, pipeline, and dataset IDs before [`init`](https://docs.platform.toloka.ai/docs/cli/reference/init) writes the agent entry points.

Create a live project and select it in one step, in a directory that has no `toloka.json` yet:

```
toloka project create cats --team-id <teamId>
toloka init
```

Creating a project requires a team. Without `--team-id`, the CLI uses the only team where your key has write access; [`toloka whoami`](https://docs.platform.toloka.ai/docs/cli/reference/auth-status) lists your teams on a `Teams:` line and marks read-only teams `(read-only)`. When several teams are writable the command refuses with `Missing team id. Pass --team-id. This account can create projects in several teams: <ids>.`; when none is writable it refuses with `This account has no writable team, so it cannot create a project.`

After a project is selected, [`toloka status`](https://docs.platform.toloka.ai/docs/cli/reference/status) prints its team ID. A directory already bound to another project keeps that binding, which takes precedence over [`project switch`](https://docs.platform.toloka.ai/docs/cli/reference/project/switch).

[`project switch`](https://docs.platform.toloka.ai/docs/cli/reference/project/switch), [`project current`](https://docs.platform.toloka.ai/docs/cli/reference/project/current), and [`project remove`](https://docs.platform.toloka.ai/docs/cli/reference/project/remove) only change the local alias registry. `remove` does not delete the live project.

To stop reconciling one tracked pipeline or dataset without deleting it from the platform, run [`toloka project untrack pipeline <name>`](https://docs.platform.toloka.ai/docs/cli/reference/project/untrack) or [`toloka project untrack dataset <name>`](https://docs.platform.toloka.ai/docs/cli/reference/project/untrack). The command changes only `toloka.json`; it previews the binding in a terminal and requires `--confirm` outside a terminal.

Print the selected project's browser-ready URL for an agent or script:

```
toloka project url
```

[`project url`](https://docs.platform.toloka.ai/docs/cli/reference/project/url) uses the same project and platform precedence as other commands, fetches the live project to resolve its team, and writes only the URL to stdout.

Credentials and the platform URL resolve separately, highest first: `--api-key` / `--base-url`, then `TOLOKA_API_KEY` / `TOLOKA_BASE_URL`, then the API key stored by [`toloka login --api-key-stdin`](https://docs.platform.toloka.ai/docs/cli/reference/login), then the browser session stored by [`toloka login`](https://docs.platform.toloka.ai/docs/cli/reference/login). With none of those, the platform is `https://platform.toloka.ai`.

The platform URL may include a path, for a gateway that serves the platform under a prefix. Requests keep that path: with `TOLOKA_BASE_URL=https://gateway.example/ss/pp.1`, the CLI calls `https://gateway.example/ss/pp.1/api/v2-beta/...`, with or without a trailing slash. Set only the origin when you talk to the platform directly.

### Manage shared datasets

Rows are not source. Append a JSON array, JSONL, or CSV file:

```
toloka dataset upload cat-images ./data/cat_images.jsonl
```

The CLI infers `.json`, `.jsonl`, or `.csv` from the filename and uploads the original bytes. JSON contains an array of row objects; JSONL contains one object per non-empty line; CSV uses its header row as field names and ingests every value as a string. Upload is additive. If the dataset does not exist yet and a pipeline in source declares it with at least one column, upload creates the dataset with those columns. Otherwise create it first:

```
toloka dataset create cat-images
```

The rows of a dataset created this way are stored whole; the first upload infers its columns. Field schemas are immutable after creation: you can add a column, never alter or remove one. See [Create and manage datasets](https://docs.platform.toloka.ai/docs/core/datasets.md).

[`dataset list`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/list) prints live name and id. [`dataset fields <name>`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/fields) prints inferred `field()` TypeScript, or `Dataset <name> has no inferred fields yet.` Inference runs on the file-upload path; rows added another way can leave this empty even when the dataset holds items. [`dataset fields add <name> <field>...`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/fields/add) (or `--all`) turns top-level fields of the uploaded rows into dataset fields, so filters, `--balance-by`, and split columns can read their values; later uploads fill them too.

[`dataset load <name> --out ./data/rows.jsonl`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/load) starts a platform export, waits (default 60 seconds), downloads the JSON array, and writes JSONL. Pass `--timeout` in milliseconds, for example `--timeout 120000`. `--limit` slices after that download; it still waits for the full export. Failed downloads leave `--out` untouched.

Duplicate live names must be addressed by id.

## Data Labeling

### Adopt a live project

To edit an existing project, import its pipelines as TypeScript source. Every pipeline in the project must already bind a dataset, or import stops with `Every imported pipeline must have a bound dataset.` Two pipelines that bind different datasets with the same name also stop import: `Project has multiple referenced datasets named "<name>".` Rename one live dataset first.

```
toloka import
toloka plan
```

Omit the id to import the selected project, or pass `pp.…` to import that id and bind it. [`import`](https://docs.platform.toloka.ai/docs/cli/reference/import) records live ids in `toloka.json`. Do not hand-edit those ids. If `pipelines/` already exists, import exits with `Folder already exists: <path>. Pass --force to replace it.` Pass `-f` or `--force` to replace it. A freshly imported project prints `No changes.` If [`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan) prints anything else, the source and the platform disagree — read the diff before you edit.

To author a project from scratch, start with the [pipeline authoring SDK](https://docs.platform.toloka.ai/docs/sdk/pipelines.md) and return here for [`validate`](https://docs.platform.toloka.ai/docs/cli/reference/validate), [`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan), and [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply).

### Reconcile pipeline source

TypeScript source is the desired state. [`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan) reads source and live state and prints the difference. [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) makes the platform match, until a pipeline has a run whose deploy did not fail. After that, a graph write returns `409` and later edits need a clone. Run [`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan) again and require `No changes.`

```
toloka check
toloka validate
toloka plan
toloka apply
toloka plan
```

[`check`](https://docs.platform.toloka.ai/docs/cli/reference/check) is credential-free. It runs project TypeScript, automatic labeling-interface typechecking, Vitest, and required typed `test.code`, `test.ui`, and `test.pipeline` coverage. Exit `1` means source, types, tests, or required coverage failed. Exit `2` means a required checker could not run.

[`check`](https://docs.platform.toloka.ai/docs/cli/reference/check) also reports `platform-rules` warnings for the rules the platform enforces when it writes a graph. Each warning names the node and the setting path that breaks the rule. The rules cover:

* node names
* quality criteria
* Human QA review time
* price
* data collection media
* exam limits
* onboarding course structure and block contents
* the 150,000-character limit on one node setting

These warnings do not fail [`check`](https://docs.platform.toloka.ai/docs/cli/reference/check), but [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) reruns the checks before resolving credentials or writing platform state and refuses to write a pipeline that violates a rule. Onboarding content is checked locally, except whether worked examples run against the labeling interface; the platform's own node checks cover that.

[`validate`](https://docs.platform.toloka.ai/docs/cli/reference/validate) posts each bound graph and prints `valid`, `invalid` with issue details, `checks-pending` while the platform's own node checks have not finished, or `skipped` when the pipeline or its dataset is not on the platform yet. Only `invalid` exits `1`. It does not write the graph. Those platform node checks are tracked separately from [`toloka check`](https://docs.platform.toloka.ai/docs/cli/reference/check).

[`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan) is read-only. Matching source prints `No changes.` Otherwise it prints `Plan: N changes` and one line per change (`+` added, `~` changed, `-` removed, `!` missing).

[`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) refuses before any write when:

* [`toloka check`](https://docs.platform.toloka.ai/docs/cli/reference/check) reports a failed or missing required check, or a checker that could not run.
* a new or changed pipeline violates a rule reported by `platform-rules` — `The platform would reject these pipelines:`, followed by one `- <directory>, node <node>, <setting>: <reason>` line per issue.
* a pipeline in `toloka.json` is absent from source — `Refusing to delete pipelines absent from source: <directories>.`
* a dataset in `toloka.json` is named by no pipeline — `Refusing to delete datasets absent from source: <names>. Dataset items are never deleted.`
* a code node names a secret the project does not have — `Required secrets are missing: <names>. Run toloka secret set <name> before apply.`
* a declared field exists with a different JSON Schema — `Dataset field schemas conflict with source: <dataset>.<field>. Existing fields are never rewritten.`

If the platform rejects a graph, the CLI prints the `400` body, starting with `Pipeline graph validation failed (<n> errors):`. Each following line names one node and setting path, for example `- node <name>, <setting path>: <reason>`.

After a failed [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply), run [`toloka plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan), inspect the changes, fix the reported errors, and rerun [`toloka apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply). For a new pipeline, a rejected graph creates no dataset fields. Earlier successful pipeline imports remain, and retrying binds their datasets. For an existing pipeline, fields added before a rejected graph write remain and cannot be changed or deleted.

On success it prints `No changes.` or `Applied N planned changes with M platform writes to project <projectId>.`

[`toloka status`](https://docs.platform.toloka.ai/docs/cli/reference/status) (no [`pipeline`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline) prefix) is project health: id, name, team, live pipeline / dataset / secret counts, and either `Source has no pending changes.` or `Source has N pending change(s).` That last line is the same test as [`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan), not a claim that every live resource is declared in source.

### Set pipeline secrets

Put secret names in node settings and keep values out of source:

```
toloka secret set OPENAI_API_KEY --from-env OPENAI_API_KEY
```

The value is read from that environment variable, or from stdin if you omit `--from-env`. Node settings reference the name; they never carry the value.

### Price and start a pipeline run

> [!WARNING]
>
> Starting a pipeline run can charge your team's balance. A single pipeline run [launches at most 10,000 items](https://docs.platform.toloka.ai/docs/data/guides/label-at-volume.md). Forecast Expected and Maximum totals first; a pipeline with no billed nodes may show no charge.

```
toloka pipeline cost cat-labeling
toloka pipeline cost cat-labeling --item-limit 10
toloka pipeline run cat-labeling
```

`--item-limit` on `cost` is a forecast override. It does not change the pipeline.

When a node has a warning, `cost` prints a `Warnings` section with one line per node. See [Pipeline pricing](https://docs.platform.toloka.ai/docs/data/concepts/pricing.md) for how branching affects Expected and Maximum totals.

[`pipeline run`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/run) starts a run of the live pipeline — the same operation as the API's start-run call. It does not wait. Exit code `0` means the platform accepted the run, not that labeling finished. A follow-up line tells you to poll [`toloka pipeline status`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/status) or re-run with `--wait`.

Pass the live pipeline name or ID; use the ID when names are duplicated. If you omit the argument:

| Pipelines in the project | Result |
| - | - |
| None | `This project has no pipelines.` |
| One | Pass its name or ID; the CLI does not select it automatically. |
| Several, in a terminal | Select from the picker. |
| Several, without a terminal | Pass a name or ID: `This project tracks several pipelines, so name one: …` |

With `--wait`, the CLI polls until the run succeeds or fails, or until the wait window closes (default 60 seconds; pass `--timeout` in milliseconds). Exit codes:

| Code | Meaning |
| - | - |
| 0 | The run succeeded, or `--wait` was omitted and the run was accepted. |
| 1 | The run failed. |
| 2 | The wait window closed while the run was still going. |

A run can remain in progress beyond the wait timeout. Use [`toloka pipeline status <name>`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/status) to check it again; [`toloka pipeline results <runId> --failed`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/results) lists failed items.

[`pipeline cancel <runId>`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/cancel) requests cancellation. Already-completed items are unaffected. Cancellation is asynchronous — poll [`pipeline status`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/status) until the run settles. After cancel, the run reports `failed` with the error `Run canceled`. Cancel works only once the run is deployed. Canceling during deploy, canceling twice, or canceling while the run is being finalized returns `409`. See [Resume or cancel a run](https://docs.platform.toloka.ai/docs/data/guides/pause-resume-cancel.md).

By default, cancellation waits for items in Human QA to finish review. Add `--accept-without-review` to accept waiting items without review now. With either choice, you pay for work recorded before each canceled item ends on its node; the unused reserved amount returns to your balance. See [Items that wait for Human QA](https://docs.platform.toloka.ai/docs/data/guides/pause-resume-cancel.md#items-that-wait-for-human-qa) for the 14-day timeout, items already under review, and where accepted answers appear.

A second [`pipeline run`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/run) on the same live pipeline returns `409` with `Cannot create run for pipeline <pipelineId> because it already has an active run.` After a successful run, [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) that would write a new graph also returns `409` with `Cannot create a new checkpoint for pipeline <pipelineId> because it has an active run.` Clone the pipeline in the platform, then import or re-point. A failed deploy is the exception: it frees the same pipeline. See [One pipeline, one run](https://docs.platform.toloka.ai/docs/data/concepts/overview.md#one-pipeline-one-run).

Starting a run through the CLI uses the same lint gate as the web app. Unfinished built-in lints, configuration errors, and failed checks block the deploy.

## Train

Train uses the shared sign-in, project selection, and dataset commands above, but it does not use the TypeScript pipeline-authoring SDK. A Training draft, Training Run, Model, and Model Version are Train resources in the selected project.

Create a Training with `--dataset <name-or-id>` or `--slice <id>`. `--dataset` prepares the dataset's split column and freezes a slice; a dataset with no split column gets an 80% train, 10% validation, 10% test split. `--slice` reuses a ready slice that freezes a split column.

Use `--split-column <name-or-id>` when there is more than one split column and `--parts <names>` to select comma-separated train parts. Validation comes from parts with the `validate` role, and test rows stay out of learning. If the slice supplies no validation rows, the platform holds out 10% of the selected train rows. See [Training dataset selections](https://docs.platform.toloka.ai/docs/train/reference/settings.md#dataset-selections) for freezing a new slice after adding data, and [Slices and split columns](https://docs.platform.toloka.ai/docs/train/reference/settings.md#slices-and-split-columns) for [`toloka dataset split`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/split), [`toloka dataset columns`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/columns), and [`toloka dataset slice`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/slice).

Use these command families for the Train lifecycle:

* [`base-model list`](https://docs.platform.toloka.ai/docs/cli/reference/base-model/list) and [`base-model get`](https://docs.platform.toloka.ai/docs/cli/reference/base-model/get) inspect the catalog you can train from.
* [`training create`](https://docs.platform.toloka.ai/docs/cli/reference/training/create), [`training get`](https://docs.platform.toloka.ai/docs/cli/reference/training/get), and [`training update`](https://docs.platform.toloka.ai/docs/cli/reference/training/update) manage an editable Training draft.
* [`training cost`](https://docs.platform.toloka.ai/docs/cli/reference/training/cost) calculates and validates a free cost estimate.
* [`training run`](https://docs.platform.toloka.ai/docs/cli/reference/training/run) starts a billed Training Run. Use [`training runs`](https://docs.platform.toloka.ai/docs/cli/reference/training/runs), [`training status`](https://docs.platform.toloka.ai/docs/cli/reference/training/status), [`training metrics`](https://docs.platform.toloka.ai/docs/cli/reference/training/metrics), and [`training logs`](https://docs.platform.toloka.ai/docs/cli/reference/training/logs) to monitor it.
* [`training resume`](https://docs.platform.toloka.ai/docs/cli/reference/training/resume) and [`training cancel`](https://docs.platform.toloka.ai/docs/cli/reference/training/cancel) control eligible blocked or active Training Runs.
* [`model list`](https://docs.platform.toloka.ai/docs/cli/reference/model/list), [`model get`](https://docs.platform.toloka.ai/docs/cli/reference/model/get), [`model versions`](https://docs.platform.toloka.ai/docs/cli/reference/model/versions), and [`model version download`](https://docs.platform.toloka.ai/docs/cli/reference/model/version/download) inspect and download published outputs. [`model create`](https://docs.platform.toloka.ai/docs/cli/reference/model/create) and [`model archive`](https://docs.platform.toloka.ai/docs/cli/reference/model/archive) manage Model containers.

> [!WARNING]
>
> Starting a Training Run places a hold for the estimate's maximum charge on the team balance. Review [Training cost](https://docs.platform.toloka.ai/docs/train/concepts/cost.md) before you run it; pipeline Expected and Maximum forecasts do not describe Training settlement.

Follow [Train your first model](https://docs.platform.toloka.ai/docs/train/get-started/first-trained-model.md) for the first end-to-end CLI workflow. Use [Fine-tune a model](https://docs.platform.toloka.ai/docs/train/guides/fine-tune.md) or [Compress a prompt with gisting](https://docs.platform.toloka.ai/docs/train/guides/gist.md) for method-specific commands and settings.

## Command reference

The [CLI reference](https://docs.platform.toloka.ai/docs/cli/reference.md) lists every public command, with its arguments, options, defaults, and inherited global flags. It also covers [environment variables](https://docs.platform.toloka.ai/docs/cli/reference.md#environment-variables) and [exit codes](https://docs.platform.toloka.ai/docs/cli/reference.md#exit-codes).

Output is colored on a terminal. Set `NO_COLOR=1` or `TERM=dumb` to turn color off, or `FORCE_COLOR=1` to keep it when piping.

## Shared CLI behavior

### Usage data

By default, the CLI sends usage reports and reports exceptions from failed commands. Running an authenticated command links reports to your Toloka account. Reports include the command type, duration, exit code, outcome or error code, HTTP status and request ID when available, and SDK and Bun versions. Exception reports use a generated error summary; invalid commands and flags do not produce exception reports.

These reports exclude raw arguments, flag values, environment variables, API keys, secret names, platform addresses, local paths, project IDs, original error messages and stack traces, response bodies, and source context.

Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to turn this off. `TOLOKA_TELEMETRY=1` turns it on even when `DO_NOT_TRACK=1` is set. CI is off unless you set `TOLOKA_TELEMETRY=1`. Accepted values for on: `1`, `true`, `yes`, `on`. For off: `0`, `false`, `no`, `off`.

[`toloka report <report.md>`](https://docs.platform.toloka.ai/docs/cli/reference/report) is separate: it previews the file and, after you confirm, sends its full text to Toloka. It needs usage reporting on. With it off, the command stops with `Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.`

### Sharp edges

* Dataset columns are immutable. [`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan) reports a schema conflict and [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) refuses rather than rewriting data. Declare a new column, or bind the pipeline to a new dataset.
* No live platform resource is deleted implicitly. A pipeline or dataset tracked in `toloka.json` but absent from source is reported and refused, not dropped. Restore its source or binding, or run [`toloka project untrack pipeline <name>`](https://docs.platform.toloka.ai/docs/cli/reference/project/untrack) or [`toloka project untrack dataset <name>`](https://docs.platform.toloka.ai/docs/cli/reference/project/untrack) to stop reconciling it while leaving it live. The UI's **Hide** action does not delete a resource or remove its local tracking, so hiding does not resolve this error. There is no `toloka destroy`. [`import`](https://docs.platform.toloka.ai/docs/cli/reference/import) refuses an existing `pipelines/` directory unless you pass `--force`.
* `toloka.json` records exactly one `projectId`. A second project needs a second checkout, or `--project-id` with state files kept apart.
* Reusing an upload filename is allowed. Uploads append rows without deduplicating them, even when the filename is unchanged.
* When an upload fails, the CLI cancels the pending upload itself. If that cancel fails too, later uploads return `Another upload is already in progress. Complete or cancel it before starting a new one.`, and there is no manual cancel. Load into a new dataset and report the dataset id.
* [`pipeline run`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/run) can fail with `500` `Internal error`. Check [`toloka pipeline runs <name>`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/runs) before retrying; a run may already have been created.
* When the dataset export behind [`dataset load`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/load) fails, the command stops with `Dataset export <exportId> succeeded without a download URL.` and a hint to report a defect. The message does not include the export's error. Read it with `GET /exports/:exportId` in the [HTTP API](https://docs.platform.toloka.ai/docs/api-reference.md): a failed export has `status` `failed` and an `error` with `code` and `message`. Correct the cause before retrying. Use a longer `--timeout` only when the export is still running.
* Layout (canvas positions) is not authored. Existing layout is preserved; new nodes get server defaults.

### Permissions

API keys inherit their owner's team permissions; see [HTTP API permissions](https://docs.platform.toloka.ai/docs/api-reference.md#permissions) for `403` and `404` responses. [`pipeline results`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/results) on a read-only key withholds failure details: `Failure details are withheld because this API key has read access only. A key with write access on the project sees them.`

[`project add`](https://docs.platform.toloka.ai/docs/cli/reference/project/add), [`project switch`](https://docs.platform.toloka.ai/docs/cli/reference/project/switch), [`project remove`](https://docs.platform.toloka.ai/docs/cli/reference/project/remove), and [`project create`](https://docs.platform.toloka.ai/docs/cli/reference/project/create) refuse `--api-key` / `--base-url` / `TOLOKA_API_KEY` / `TOLOKA_BASE_URL` when those would select a different key or platform than the stored file.

### Errors and hints

A failing command prints its message to stderr and exits `1`. Most messages are followed by a `Hint: …` line naming the next command to run, for example `Hint: Run toloka training list and pass the training id (trg.…).`; messages that already spell out the remedy carry no hint. Platform failures print the API status and body first, followed by a hint chosen by status: `401`/`403` point at [`toloka whoami`](https://docs.platform.toloka.ai/docs/cli/reference/auth-status) and [`toloka login`](https://docs.platform.toloka.ai/docs/cli/reference/login), `404` at the selected project and the matching list command, `429` asks you to wait, and `5xx` asks you to retry and then file a report with [`toloka report <report.md>`](https://docs.platform.toloka.ai/docs/cli/reference/report). Every platform error also carries its `request id`; quote it when you report a problem.

### Troubleshooting

Match the exact text the CLI prints:

| Response | Cause | What to do |
| - | - | - |
| `Not logged in. Run toloka login once to sign in through your browser on this machine:` | No flag, env, stored key, or browser login. | Run [`toloka login`](https://docs.platform.toloka.ai/docs/cli/reference/login), or set `TOLOKA_API_KEY`. |
| `Could not authenticate against <url>: …` / `Nothing was saved.` | The login probe failed. The second line says which: a rejected key, a platform that did not answer, or a platform error. | Rejected: copy the key whole from the console that serves that URL. Did not answer: fix network access and retry. |
| `error: unknown command '<name>'` / `toloka <version> does not have it.` | The installed CLI does not define that command; `--help` does not change this and the root help is not printed. Exit code `1`. | Run the default installer again to get the latest release, then use `toloka --help` to see its commands. |
| `Rejected: …` / `Not reachable: …` / `Platform error: …` (from [`whoami`](https://docs.platform.toloka.ai/docs/cli/reference/auth-status)) | The platform rejected the login (401/403); the platform did not answer (DNS, connection, proxy); the platform failed. Exit code `1` in all three. | Rejected: run [`toloka login`](https://docs.platform.toloka.ai/docs/cli/reference/login) again. Not reachable: fix network access; the login was not evaluated. Platform error: retry later. |
| `No project selected. Run toloka project create for a new project, toloka project add for an existing project, or cd into a checkout.` | No project id in flag, env, or `toloka.json`, or the credentials-file alias is for a different platform than the URL in effect. | [`toloka project create`](https://docs.platform.toloka.ai/docs/cli/reference/project/create) or [`toloka project add`](https://docs.platform.toloka.ai/docs/cli/reference/project/add), `cd` into a checkout, or pass `--project-id`. |
| `Missing team id. Pass --team-id. …` | Your key can write in several teams, or the platform did not report your teams. | Pick a team from [`toloka whoami`](https://docs.platform.toloka.ai/docs/cli/reference/auth-status) and pass `--team-id`. |
| `Dataset field schemas conflict with source: <dataset>.<field>. Existing fields are never rewritten.` | Source declares a different JSON Schema than the live column. | Declare a new column name, or bind a new dataset. |
| `400` `Pipeline graph validation failed (<n> errors):` | The platform rejected the graph that [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) wrote. Each `- node <name>, <setting path>: <reason>` line is one broken rule. | Fix each listed setting, run [`toloka check`](https://docs.platform.toloka.ai/docs/cli/reference/check) until it reports no `platform-rules` warnings, then [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) again. |
| `The platform would reject these pipelines:` | [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) found `platform-rules` violations in a new or changed pipeline and wrote nothing. Each following line names the directory, node, and setting. | Fix the listed nodes in source; [`toloka check`](https://docs.platform.toloka.ai/docs/cli/reference/check) reports the same rules as warnings. |
| `Dataset export <exportId> succeeded without a download URL.` | The export behind [`dataset load`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/load) failed. The message does not show why. | Read the error with `GET /exports/:exportId` in the [HTTP API](https://docs.platform.toloka.ai/docs/api-reference.md), correct it, then run [`dataset load`](https://docs.platform.toloka.ai/docs/cli/reference/dataset/load) again. |
| `Required secrets are missing: <names>. Run toloka secret set <name> before apply.` | A code node names a secret the project does not have. | [`toloka secret set <name> --from-env <variable>`](https://docs.platform.toloka.ai/docs/cli/reference/secret/set), then [`plan`](https://docs.platform.toloka.ai/docs/cli/reference/plan) again. |
| `Refusing to delete pipelines absent from source: <directories>.` | Live pipelines in `toloka.json` have no matching source. | Restore the source or run [`toloka project untrack pipeline <name>`](https://docs.platform.toloka.ai/docs/cli/reference/project/untrack) to leave the live pipeline untracked. Hiding it in the UI does not resolve the error. |
| `Refusing to delete datasets absent from source: <names>. Dataset items are never deleted.` | Tracked datasets are named by no pipeline. | Restore the source binding, keep the dataset tracked, or run [`project untrack dataset <name>`](https://docs.platform.toloka.ai/docs/cli/reference/project/untrack). |
| `Another upload is already in progress. Complete or cancel it before starting a new one.` | A previous upload to that dataset is still pending because its automatic cancel failed too. There is no manual cancel. | Load into a new dataset and report the dataset id. |
| `Pass a pipeline name. This project has: <name> (<id>).` | [`pipeline`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline) was invoked without a name, there is exactly one live pipeline, and no picker ran. | Pass the name or id. Several pipelines without a terminal print `This project tracks several pipelines, so name one: …` |
| `Stopped waiting for run <id>; it has not reached a terminal state yet and may still be running.` | `--wait` hit `--timeout` (default 60 seconds). | [`toloka pipeline status <name>`](https://docs.platform.toloka.ai/docs/cli/reference/pipeline/status); raise `--timeout`. |
| `401` `Unauthenticated` | The key is missing or invalid. | Send a working key; see [Programmatic access (API)](https://docs.platform.toloka.ai/docs/api-reference.md#troubleshooting). |
| `Cannot create run for pipeline <pipelineId> because it already has an active run.` | The pipeline already has a run whose deploy did not fail. | Clone the pipeline in the platform, then import or re-point. |
| `Cannot create a new checkpoint for pipeline <pipelineId> because it has an active run.` | [`apply`](https://docs.platform.toloka.ai/docs/cli/reference/apply) tried to write a graph after a run whose deploy did not fail. | Clone the pipeline, then import or re-point. |

For every other platform message, search [Errors and how to fix them](https://docs.platform.toloka.ai/docs/data/reference/errors.md).

## Related

* [Projects](https://docs.platform.toloka.ai/docs/core/projects.md) — understand the shared container selected by the CLI
* [Pipelines as code](https://docs.platform.toloka.ai/docs/sdk/pipelines.md) — define Data Labeling pipelines, fields, nodes, and connections
* [HTTP API](https://docs.platform.toloka.ai/docs/api-reference.md) — automate both products without the CLI
* [How Training works](https://docs.platform.toloka.ai/docs/train/concepts/how-training-works.md) — understand Training, Training Runs, Models, and Model Versions
* [Create and manage datasets](https://docs.platform.toloka.ai/docs/core/datasets.md) — use the data contract shared by both products
* [Label a large dataset in batches](https://docs.platform.toloka.ai/docs/data/guides/label-at-volume.md) — work within the pipeline-run cap and clone cycle
* [Pipeline pricing](https://docs.platform.toloka.ai/docs/data/concepts/pricing.md) — estimate Data Labeling pipeline runs
* [Training cost](https://docs.platform.toloka.ai/docs/train/concepts/cost.md) — estimate and fund Training Runs
* [Billing](https://docs.platform.toloka.ai/docs/core/billing.md) — compare how both products use the team balance
* [Dataset and pipeline errors](https://docs.platform.toloka.ai/docs/data/reference/errors.md) — find customer-visible Data Labeling errors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.