> For the complete documentation index, see [llms.txt](https://argos-ci.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argos-ci.com/docs/reference/argos-command-line-interface-cli.md). # CLI The Argos command-line interface (CLI) uploads screenshots, deploys static builds, and lets you inspect and review builds from a terminal, a CI pipeline, or an AI agent. It is distributed as the [`@argos-ci/cli`](https://www.npmjs.com/package/@argos-ci/cli) npm package; the source code is available on [GitHub](https://github.com/argos-ci/argos-javascript/tree/main/packages/cli). The examples on this page call the `argos` binary directly. Depending on your package manager, run it with `npm exec -- argos`, `yarn run argos`, `pnpm exec -- argos`, or `bun x argos`. ### Installation The CLI requires **Node.js 22 or later**. Install it as a dev dependency: {% tabs %} {% tab title="npm" %} ``` npm i --save-dev @argos-ci/cli ``` {% endtab %} {% tab title="yarn" %} ``` yarn add --dev @argos-ci/cli ``` {% endtab %} {% tab title="pnpm" %} ``` pnpm add --save-dev @argos-ci/cli ``` {% endtab %} {% tab title="bun" %} ``` bun add --dev @argos-ci/cli ``` {% endtab %} {% endtabs %} ### Authentication Authentication depends on where the CLI runs: * **In CI**, set the `ARGOS_TOKEN` environment variable to your project token (from **Settings → General → Token**), usually as a CI secret. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication.md) to avoid managing a secret. * **Locally**, sign in once with the browser-based login flow: ```bash argos login ``` `argos login` authorizes the CLI and stores a user token on your machine. This token is used by commands that act as a user, such as submitting a review. Commands resolve authentication in this order: 1. The `--token ` argument. 2. The `ARGOS_TOKEN` environment variable. 3. The token stored by `argos login`. {% hint style="warning" %} Do not use `argos login` in CI. CI uploads should use `ARGOS_TOKEN` or [GitHub OIDC authentication](/docs/learn/integrations/github-actions-authentication.md). {% endhint %} #### Project tokens and personal access tokens Uploads and read-only commands — `build get`, `build snapshots`, `test get`, `test changes` — work with a **project token**. Anything attributed to a user requires a **personal access token**, because the action is checked against that user's project permissions: submitting or dismissing a review, posting comments, and ignoring a change. To create a personal access token manually, go to your personal account settings, open **Tokens**, then select **Generate new token**. ![Personal settings tokens page](/files/bb1f094cf54d5eef3adc9f7964dc85a49b9c5dbb) *A personal settings tokens page* ## Commands Run `argos --help` for a command's exact arguments, flags, and defaults — the CLI is the source of truth for those. This page covers what each command is for, and the things `--help` can't tell you. | Command | What it does | | -------------------------------------- | ----------------------------------------------------------------- | | `upload ` | Upload snapshots from a directory and create a build. | | `finalize` | Close a parallel build once every shard has uploaded. | | `skip` | Create a skipped build so a required check still reports success. | | `deploy ` | Deploy a static build (Storybook or any static site). | | `build get ` | Fetch a build's status, branch, commit, stats, and URL. | | `build snapshots ` | Fetch a build's snapshot diffs, with flakiness data on each. | | `test get ` | Fetch a test with its flakiness metrics. | | `test changes ` | List a test's distinct changes, most frequent first. | | `change ignore \| unignore ` | Silence a flaky change, or bring it back under review. | | `review create \| list \| dismiss` | Submit, list, and dismiss reviews on a build. | | `comment ` | List, post, and act on the comments on a build. | | `test comment ` | The same, on the comments on a test. | | `login`, `logout`, `whoami` | Manage the CLI's user session. | | `create-project ` | Create a project in an account you administer. | | `analytics` | Fetch build and screenshot metrics for an account. | | `help [command]` | Display the available commands and options. | ### Uploading from CI `upload` is the command that creates a build. Point it at the directory holding your snapshots: ```bash argos upload ./screenshots ``` By default it uploads `**/*.{png,jpg,jpeg}`; narrow or widen that with `--files` and `--ignore`. Several flags map onto concepts documented elsewhere: * `--mode` switches between [build modes](/docs/learn/platform-fundamentals/build-modes.md) (`ci` by default, or `monitoring`). * `--parallel`, `--parallel-total`, `--parallel-index` and `--parallel-nonce` drive [parallel testing](/docs/learn/how-to-guides/ci-pipelines/parallel-testing-sharding.md). * `--subset` marks a [subset build](/docs/learn/how-to-guides/ci-pipelines/subset-builds.md). * `--build-name` runs [multiple builds on a single commit](/docs/learn/how-to-guides/ci-pipelines/monorepos-setup.md). * `--reference-branch` and `--reference-commit` pin the [baseline](/docs/learn/platform-fundamentals/baseline-build.md) instead of letting Argos resolve it. * `--threshold` sets diff sensitivity between 0 and 1 — the higher the threshold, the less sensitive the comparison. Most of these also read an `ARGOS_*` environment variable, which is usually how you set them in CI. **`finalize`** closes a [parallel build](/docs/learn/how-to-guides/ci-pipelines/parallel-testing-sharding.md) running in finalize mode (`ARGOS_PARALLEL_TOTAL=-1`). Run it once every upload has completed — Argos then aggregates the shards and starts the comparison: ```bash argos finalize ``` The shards are matched by their nonce, read from `--parallel-nonce` or `ARGOS_PARALLEL_NONCE`. In most CI environments the nonce is detected automatically, so no flag is needed as long as `finalize` runs in the same pipeline as the uploads. When every upload step is conditional — skipped by a task cache such as Turborepo or Nx, or by change detection — a run may produce no shard at all. Use `--skip-if-empty` to create a [skipped build](/docs/learn/how-to-guides/ci-pipelines/skipping-a-build.md) in that case, so a required Argos status check still reports success: ```bash argos finalize --skip-if-empty --build-name unit ``` **`skip`** creates that same [skipped build](/docs/learn/how-to-guides/ci-pipelines/skipping-a-build.md) directly: no screenshots, no comparison, an immediately successful status. It keeps a required Argos check green on commits where you intentionally don't run visual tests. Use `--build-name` to match the check you want to satisfy. #### Snapshot size limit Each snapshot uploaded to Argos is limited to **50 MB**. This applies to every artifact type — a screenshot, a [non-image snapshot](#compare-non-image-files), or a [Playwright trace](/docs/reference/playwright.md). Files larger than 50 MB are skipped and won't appear in your build. A build is also limited to **5,000 screenshots**. Beyond that, the upload is rejected with an error — use [parallel mode](/docs/learn/how-to-guides/ci-pipelines/parallel-testing-sharding.md) to split a larger test suite across several uploads. #### Compare non-image files Use `-f` or `--files` to upload text-based artifacts such as JSON, YAML, XML, HTML, Markdown, CSS, or JavaScript files. See [Compare non-image files](/docs/learn/how-to-guides/visual-coverage/compare-non-image-files.md) for examples and the full list of supported content types. #### Specify the project Use `--project ` to set the Argos project slug (`account/project-name`). This disambiguates [tokenless authentication](/docs/learn/integrations/github-actions-authentication.md#tokenless-authentication) when multiple Argos projects are linked to the same repository: ```bash argos upload ./screenshots --project my-account/my-project ``` #### Override Git detection `argos upload` detects the commit, branch, and pull request from your CI environment — or from the local Git repository when running outside CI. To override detection, set these environment variables (there are no flag equivalents): | Environment variable | Description | | ---------------------- | ----------------------------------------------------------------------------------- | | `ARGOS_COMMIT` | Commit SHA of the build. Must be a full 40-character SHA — short SHAs are rejected. | | `ARGOS_BRANCH` | Branch of the build. | | `ARGOS_PR_NUMBER` | Number of the pull request associated with the build. | | `ARGOS_PR_HEAD_COMMIT` | Head commit of the pull request. | | `ARGOS_PR_BASE_BRANCH` | Base branch of the pull request. | In a non-Git environment, `ARGOS_COMMIT` and `ARGOS_BRANCH` are required — without them the upload fails with "Argos requires a branch and a commit to be set". To find the [baseline](/docs/learn/platform-fundamentals/baseline-build.md), Argos resolves ancestor commits. When your project is connected to GitHub or GitLab, this happens server-side. Otherwise the CLI fetches history from the `origin` remote — in a repository without `origin` (for example a local mirror), it falls back to the local history, so make sure enough history is available locally, or pin the baseline explicitly with `--reference-commit` and `--reference-branch`. Parent commits are always computed automatically and cannot be set manually. To see what the CLI detected, run it with debug output: ```bash DEBUG=@argos-ci/core argos upload ./screenshots ``` ### Deploying a static build `deploy` publishes a static site — a Storybook, a docs build, anything — to Argos. See [Deployments](/docs/learn/deployments.md) for the overview: ```bash argos deploy ./storybook-static ``` By default this creates a **preview** deployment. Add `--prod` to force a **production** one regardless of the branch. If the branch matches the project's production branch pattern, it is created as production even without the flag — see [Environments](/docs/learn/deployments/environments.md) for the full rules. `deploy` uses the same [authentication](#authentication) as `upload`. ### Inspecting builds and tests These commands read data, so a project token is enough. A `` is a build number or a full Argos build URL; with a number, add `--project team/project`, since a URL already carries it. ```bash argos build get https://app.argos-ci.com/team/project/builds/72652 argos build snapshots 72652 --project team/project --needs-review --json ``` `build get` returns the build's status, branch, commit, stats, and URL. `build snapshots` returns its diffs — each with a status, score, diff mask URL, baseline file, current file, and the metadata your SDK provided. Add `--needs-review` to get only the diffs awaiting a decision. When a diff belongs to a tracked test it also carries that test's [flakiness metrics](/docs/learn/reliability-and-flakiness/flaky-test-detection.md) under `test.metrics`, and — when the diff is a change — its ignore state and occurrence count under `change`. `--metrics-period` sets the window those are computed over (`24h`, `3d`, `7d`, `30d`, `90d`; defaults to `7d`). A high occurrence count or flakiness score is a strong flakiness signal. Take the diff's `test.id` and look at the whole test — the CLI equivalent of the [test page](/docs/learn/reliability-and-flakiness/test-page.md): ```bash argos test get --json argos test changes --json ``` `test get` returns the test's name, build name, and `ongoing` or `removed` status; its `metrics` for the period; a `series` of the same counts bucketed over time, which distinguishes a test that has always been flaky from one that started recently; and `firstSeenChange` / `lastSeenChange`. `test changes` lists its distinct changes, the ones that came back most often first. Each carries its `id`, whether it is `ignored`, its `occurrences`, when it was `firstSeen` and `lastSeen`, and the `diff` of its latest occurrence with the mask, baseline, and captured screenshot URLs. `--ignored true|false` narrows the list to ignored or still-reviewable changes. A `` carries the project name but not the account, so pass `--project owner/project` (or `ARGOS_PROJECT`) — unless you authenticate with a project token, which already identifies its own project. ### Silencing a flaky change `change ignore` stops a flaky change from requiring review, auto-approving it on future builds. `change unignore` reverses that. Both are the CLI equivalent of the **Ignore** button in a build review — see [Ignore changes](/docs/learn/reliability-and-flakiness/flaky-test-detection.md#ignore-changes) — and both need a [personal access token](#project-tokens-and-personal-access-tokens) with review permission. The `` comes from a diff's `change.id` in `argos build snapshots --json`, or from `argos test changes --json`. Like a test id it doesn't carry the account, so pass the project: ```bash argos change ignore --project team/project argos change unignore --project team/project ``` The ignore feature must be enabled for the project (**Project Settings → Flaky detection**, on by default). Argos can also [ignore recurring flaky changes automatically](/docs/learn/reliability-and-flakiness/flaky-test-detection.md#automatically-ignore-recurring-flaky-changes). To let an agent do the investigation instead, see [Fix flaky tests with AI agents](/docs/learn/reliability-and-flakiness/fix-flaky-tests-with-ai-agents.md). ### Reviewing and commenting Every command in this group acts as a user, so they all require a [personal access token](#project-tokens-and-personal-access-tokens). ```bash argos review create --event approve argos review create --event reject --body "The header spacing regressed." argos review list --json argos review dismiss ``` `--event` is one of `approve`, `reject`, or `comment`, and `--body` / `--body-file` attach a Markdown summary. Dismissing a review stops it counting toward the [build status](/docs/learn/review-workflow/review-a-build.md#how-reviews-decide-the-build-status). Comments live in two groups: `comment` for a [build's review discussion](/docs/learn/review-workflow/review-a-build.md#comment-on-exactly-what-changed), and `test comment` for a [test's own thread](/docs/learn/reliability-and-flakiness/test-page.md#discuss-the-test-with-your-team). Both take the same subcommands — `list`, `create`, `get`, `edit`, `delete`, `resolve`, `unresolve`, `react`, `unreact`, `subscribe`, `unsubscribe`: ```bash argos comment list --json argos test comment create --project team/project --body "Flaky since the carousel landed." ``` Run `argos comment --help` or `argos test comment --help` for each subcommand's arguments. ### Managing your session `login`, `logout` and `whoami` manage the CLI's user session — see [Authentication](#authentication): ```bash argos login # Log in to Argos by opening your browser argos whoami # Display the user authenticated with the current token argos logout # Log out from Argos ``` ### Account commands `create-project` creates a project in an account you administer: ```bash argos create-project my-new-project --account my-team ``` `analytics` fetches build and screenshot metrics for an account. It reports totals and a per-period series for both screenshots and builds — including how many detected changes and how many were accepted or rejected — broken down by project: ```bash argos analytics --account my-team --from 2026-01-01 --group-by month --json ``` `--from` defaults to 30 days ago and `--to` to now, with a range capped at 365 days; `--group-by` buckets by `day`, `week`, or `month`; and `--project` filters by project name, repeated for several. Both `create-project` and `analytics` take the account from `--account ` or `ARGOS_ACCOUNT`, and need a [personal access token](#project-tokens-and-personal-access-tokens) scoped to it. See [Analytics](/docs/learn/account-and-access/analytics.md) for the dashboard view of these metrics. ## AI agent skills The [`argos-javascript`](https://github.com/argos-ci/argos-javascript) repository includes skills that help AI agents use Argos CLI commands and review pull requests with Argos build data: * [`argos-cli`](https://github.com/argos-ci/argos-javascript/tree/main/skills/argos-cli): use Argos CLI commands, flags, authentication, and output formats. * [`argos-pr-review`](https://github.com/argos-ci/argos-javascript/tree/main/skills/argos-pr-review): review a pull request with an Argos build as visual evidence. See [Review builds with AI agents](/docs/learn/review-workflow/review-builds-with-ai-agents.md) to install and use the skills in a pull request review workflow. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://argos-ci.com/docs/reference/argos-command-line-interface-cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.