CLI
Use the Argos CLI to upload screenshots, deploy static builds, inspect builds and flaky tests, and submit reviews from scripts, local workflows, or AI agents.
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 npm package; the source code is available on GitHub.
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:
npm i --save-dev @argos-ci/cliyarn add --dev @argos-ci/clipnpm add --save-dev @argos-ci/clibun add --dev @argos-ci/cliAuthentication
Authentication depends on where the CLI runs:
In CI, set the
ARGOS_TOKENenvironment 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 to avoid managing a secret.Locally, sign in once with the browser-based login flow:
argos loginargos 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:
The
--token <token>argument.The
ARGOS_TOKENenvironment variable.The token stored by
argos login.
Do not use argos login in CI. CI uploads should use ARGOS_TOKEN or GitHub OIDC authentication.
Project tokens and personal access tokens
Uploads and read-only commands — build get, build snapshots, test list, test get, test changes, change list, project get, project deployments, project domain get — work with a project token. Anything attributed to a user requires a personal access token, because the action is checked against that user's permissions: submitting or dismissing a review, requesting reviewers, posting comments, ignoring a change, configuring a project, and administering a team.
Two read-only commands are the exception: project contributor list and review reviewer list return users, so they need a personal access token to resolve them against — a project token carries no identity.
To create a personal access token manually, go to your personal account settings, open Tokens, then select Generate new token.
A personal settings tokens page
Commands
Run argos <command> --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.
upload <directory>
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 <directory>
Deploy a static build (Storybook or any static site).
build get <buildReference>
Fetch a build's status, branch, commit, stats, and URL.
build snapshots <buildReference>
Fetch a build's snapshot diffs, with flakiness data on each.
build subscribe | unsubscribe
Follow or stop following a build's notifications.
test list
List a project's tests, flakiest first.
test get <testId>
Fetch a test with its flakiness metrics.
test changes <testId>
List a test's distinct changes, most frequent first.
test subscribe | unsubscribe <testId>
Follow or stop following a test's notifications.
change list
List the changes currently ignored in a project.
change ignore | unignore <changeId>
Silence a flaky change, or bring it back under review.
review create | list | dismiss
Submit, list, and dismiss reviews on a build.
review reviewer list | add | remove
List, request, and cancel review requests on a build.
comment <subcommand>
List, post, and act on the comments on a build.
test comment <subcommand>
The same, on the comments on a test.
project get | update
Read a project's settings, and change them one flag at a time.
project transfer
Move a project to another account.
project contributor list | set | remove
Manage who can reach a project outside the team's own roles.
project deployments
List a project's deployments, most recent first.
project domain get | set
Read or set the domain production deployments are served on.
automation <subcommand>
List, create, replace, and deactivate a project's automation rules.
account get | update
Read plan and usage, and set the role users get when they join.
account member <subcommand>
List a team's members, change their role, remove them.
account invite <subcommand>
Invite people, cancel invites, rotate the invite link.
account domain <subcommand>
Manage the email domains a team is open to.
login, logout, whoami
Manage the CLI's user session.
create-project <name>
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:
By default it uploads **/*.{png,jpg,jpeg}; narrow or widen that with --files and --ignore. Several flags map onto concepts documented elsewhere:
--modeswitches between build modes (ciby default, ormonitoring).--parallel,--parallel-total,--parallel-indexand--parallel-noncedrive parallel testing.--subsetmarks a subset build.--build-nameruns multiple builds on a single commit.--reference-branchand--reference-commitpin the baseline instead of letting Argos resolve it.--thresholdsets 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 running in finalize mode (ARGOS_PARALLEL_TOTAL=-1). Run it once every upload has completed — Argos then aggregates the shards and starts the comparison:
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 in that case, so a required Argos status check still reports success:
skip creates that same skipped build 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, or a Playwright trace. 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 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 for examples and the full list of supported content types.
Specify the project
Use --project <slug> to set the Argos project slug (account/project-name). This disambiguates tokenless authentication when multiple Argos projects are linked to the same repository:
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):
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, 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:
Deploying a static build
deploy publishes a static site — a Storybook, a docs build, anything — to Argos. See Deployments for the overview:
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 for the full rules.
deploy uses the same authentication as upload.
Inspecting builds and tests
These commands read data, so a project token is enough. A <buildReference> is a build number or a full Argos build URL; with a number, add --project team/project, since a URL already carries it.
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 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).
To start from the project rather than from a build, test list returns the tests currently running in it, flakiest first — the first page is your flakiness backlog:
A test is listed when it appeared in the latest reference build of its build name, so tests that were deleted, renamed, or skipped drop out on their own.
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:
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 <testId> 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 — and both need a personal access token with review permission.
The <changeId> 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:
The ignore feature must be enabled for the project (Project Settings → Flaky detection, on by default). Argos can also ignore recurring flaky changes automatically.
change list audits what has been silenced so far, most recently ignored first, with the test each change belongs to. Pass any of those ids back to change unignore to bring it under review again:
To let an agent do the investigation instead, see Fix flaky tests with AI agents.
Reviewing and commenting
Every command in this group acts as a user, so they all require a personal access token.
--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.
Comments live in two groups: comment for a build's review discussion, and test comment for a test's own thread. Both take the same subcommands — list, create, get, edit, delete, resolve, unresolve, react, unreact, subscribe, unsubscribe:
Run argos comment --help or argos test comment --help for each subcommand's arguments.
review reviewer handles the review requests standing on a build. Requesting someone notifies them; requesting someone already requested is a no-op, and users without access to the project are ignored:
User ids come from argos account member list --json or argos whoami --json. You cannot request yourself.
To follow a build or a test without commenting on it, subscribe to its notifications. Unsubscribing is recorded as intentional, so Argos won't subscribe you again automatically:
Configuring a project
project get prints a project's settings; project update changes them. Only the settings you pass are touched, and every one takes an explicit value — so a script never has to guess whether an omitted flag means "false" or "leave alone":
Run argos project update --help for the full list. A few conventions are worth knowing:
Nullable settings reset to their inherited default when passed an empty value:
--default-base-branch ""falls back to the repository's default branch.--private inheritreturns the project's visibility to whatever the linked repository says.--ignore-changesand--auto-ignore-afterdrive flaky change detection;--auto-ignore-after offturns automatic ignoring off while leaving manual ignoring on.
project contributor grants access to users who aren't covered by their team role — team owners and members already reach every project, so this is for contributors:
Levels are admin, reviewer, and viewer. Revoking your own access never requires administrator rights — a contributor can always walk away from a project.
project transfer moves a project to another account, optionally renaming it on the way. You must administer both the project and the account receiving it:
project deployments and project domain cover deployments: the deployments a project has published, and the custom domain its production ones are served on. Only domains under argos-ci.live are accepted.
Automation rules
automation manages the automation rules that run when a build event matches. Rules are never deleted — deactivating one keeps its run history, which is what tells you why something fired:
create and update take the rule definition as JSON, inline with --definition or from a file with --definition-file. update replaces the whole definition, so send the events, conditions, and actions you want the rule to end up with:
Action targets must belong to the project's account: a Slack channel connected to it, or the id of a Microsoft Teams or Discord webhook registered on it. Run argos automation create --help for the example inline.
Managing a team
account get reports an account's plan and its usage for the current billing period — screenshots consumed against the plan, the consumption ratio, and the cost accrued beyond it. It's the CLI equivalent of watching your usage before it runs over:
account member lists a team's members and changes what they can reach:
Roles are owner, member, and contributor — owners administer the team, members see every project, contributors only the projects they are added to. A team can never be left without an administrator: the last member cannot be removed, and removing the second-to-last one promotes the survivor to owner.
account invite covers everything that brings someone in. Re-inviting an address that already has a pending invite refreshes it, so a lost invite can always be resent:
reset-link rotates the team's shared invite link and invalidates the previous one.
account domain opens a team to an email domain, so anyone signing up with a verified address on it joins automatically, at the team's default role. Public email providers are refused, and you must hold a verified address on the domain yourself:
Removing a domain only stops new sign-ups from joining — members who already joined through it stay. account update --default-user-level <member|contributor> sets the role given to everyone who joins through the invite link or a verified domain.
Every command in this section needs a personal access token with administrator rights on the team, and takes the account from --account <slug> or ARGOS_ACCOUNT.
Paginated lists
test list, change list, account member list, account invite list, project contributor list, project deployments, and automation list follow pagination for you, up to --limit (100 by default). Raise it to walk a longer list:
Managing your session
login, logout and whoami manage the CLI's user session — see Authentication:
Account commands
create-project creates a project in an account you administer:
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:
--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 <slug> or ARGOS_ACCOUNT, and need a personal access token scoped to it.
See Analytics for the dashboard view of these metrics.
AI agent skills
The argos-javascript repository includes skills that help AI agents use Argos CLI commands and review pull requests with Argos build data:
argos-cli: use Argos CLI commands, flags, authentication, and output formats.argos-pr-review: review a pull request with an Argos build as visual evidence.
See Review builds with AI agents to install and use the skills in a pull request review workflow.
Last updated
Was this helpful?