Skip to main content

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.

note

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.

warning

Do not use argos login in CI. CI uploads should use ARGOS_TOKEN, --token, or tokenless authentication when supported by your CI integration.

Upload Command​

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

npm exec -- argos upload ./screenshots

Debug mode​

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

DEBUG=@argos-ci/core npm exec -- argos upload ./screenshots

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.

npm exec -- argos build get <buildNumber>

You can also pass an Argos build URL directly:

npm exec -- argos build get https://app.argos-ci.com/team/project/builds/72652

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

npm exec -- argos build get https://app.argos-ci.com/team/project/builds/72652 --json

Fetch snapshot diffs​

Use build snapshots to fetch snapshot diffs for a build.

npm exec -- argos build snapshots https://app.argos-ci.com/team/project/builds/72652 --json

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

npm exec -- argos build snapshots https://app.argos-ci.com/team/project/builds/72652 --needs-review --json

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.

npm exec -- argos build review https://app.argos-ci.com/team/project/builds/72652 --conclusion approve

To reject the visual changes:

npm exec -- argos build review https://app.argos-ci.com/team/project/builds/72652 --conclusion request-changes

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

npm exec -- argos build review 72652 --project team/project --conclusion approve

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.

npm exec -- argos help upload