Ctrlk
x-twitter

Argos Command Line Interface (CLI)

Use the Argos CLI to upload screenshots, inspect builds, and create build reviews from scripts, local workflows, or AI agents.

You can access @argos-ci/cli through our npm package. The source code is available on our GitHub repository.

Installation

npm i --save-dev @argos-ci/cli

Authentication

Your configuration requirements vary depending on the command you run.

For CI uploads, set ARGOS_TOKEN as an environment variable, usually as a CI secret.

You can also specify the token with the --token=<your-repository-token> argument. However, for security reasons, we recommend using an environment variable instead.

For local review commands, sign in once with the browser-based login flow:

npm exec -- argos login

argos login authorizes the CLI and stores a user token on your machine. This token is used by commands that need to act as a user, such as creating a build review.

Do not use argos login in CI. CI uploads should use ARGOS_TOKEN, --token, or GitHub OIDC authentication

Upload Command

Use the upload command to upload screenshots stored in your ./screenshots directory.

npm exec -- argos upload ./screenshots

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.

Debug mode

You can enable debug mode by setting the DEBUG environment variable.

Deploy Command

Use the deploy command to deploy a static build (Storybook or any static site) to Argos. See Deployments for an overview of the feature.

The argument is the directory containing the static files to deploy.

Production deployments

By default, deploy creates a preview deployment. Add --prod to force a production deployment regardless of the branch:

If the branch matches the project's production branch pattern, the deployment is created as production even without --prod. See Environments for the full rules.

Authentication

deploy uses the same authentication as upload:

  1. ARGOS_TOKEN environment variable (recommended).

  2. --token <token> argument.

  3. GitHub OIDC or tokenless authentication on GitHub Actions.

Build Commands

Use build commands to fetch build metadata, fetch snapshot diffs, and create a review on a build.

Get build metadata

Use build get to fetch status, branch, commit, stats, and the build URL.

You can also pass an Argos build URL directly:

Use --json when another tool needs to parse the response:

Fetch snapshot diffs

Use build snapshots to fetch snapshot diffs for a build.

Add --needs-review to only return snapshots that need a review decision:

Each snapshot diff includes the status, score, diff mask URL, baseline file, current file, and metadata provided by the SDK.

Submit a build review

Use build review to approve a build or request changes.

To reject the visual changes:

When you pass a build number instead of a full URL, also pass the project path:

Project tokens and personal access tokens

Uploads and build reads can use a project token.

Creating a build review requires a personal access token because the review is attributed to an Argos user and checked against that user's project permissions.

To create a personal access token manually, go to your personal account settings, open Tokens, then click Generate new token.

Personal settings tokens page

A personal settings tokens page

For build review, authentication is resolved in this order:

  1. --token <token>

  2. ARGOS_TOKEN

  3. token stored by argos login

Project tokens can inspect build data, but they cannot create reviews. If ARGOS_TOKEN contains a project token, use argos login locally or pass a personal access token with --token.

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.

Help Command

To view a list of available options, use the argos help command.

Last updated

Was this helpful?