[gregberge]

Description

Resolves ARG-522: there was no one-shot way to export a project's screenshots and baselines. Until now a script had to list builds through the API, then run argos build snapshots <build> --json on each one to get the image URLs.

This adds three commands:

• argos build list: a project's builds, most recent first. Supports --branch, --commit (full SHA), --search, --limit and --project.
• argos build download <ref>: writes the screenshots a build captured into a directory (./argos-build-<number> by default, -o to change it). --json returns { build, directory, files: [{ name, status, contentType, url, path }] }.
• argos baseline download: writes the project's latest baseline. That's the screenshots of the newest build on the default branch (or --branch) that Argos can use as a baseline, for one --build-name (default) and --mode (ci).

How the baseline is found

The API's Build has no name, type or mode, and a reference build's status is just its conclusion, so the CLI can't tell a baseline build apart on its own. baseline download lists the branch's builds newest first, a page at a time, and asks POST /baseline for the first of their commits that has an eligible build. That's the same rule Argos applies when it picks a baseline (complete, tests passed, not a subset, approved, not rejected). It stops after 10 pages (1,000 builds). Failure screenshots are left out, since Argos never compares them.

POST /baseline only accepts a project token, so with a personal access token (including argos login) the command fails before writing anything and says to use ARGOS_TOKEN. A backend endpoint that accepts personal tokens could lift that later without changing the command.

How files are written

• Names become paths. Each screenshot is saved under its snapshot name, so screenshots uploaded from a directory come back under the same paths (screenshots/nested/alicia.jpg).
• Existing image extensions are kept. argos upload stores JPEGs as PNG under their .jpg name, and changing the extension would break re-upload. A name with no image extension (Storybook story names) gets one from the content type.
• Nothing escapes the directory. . and .. segments and leading slashes are dropped, and on Windows the characters it rejects are replaced.
• No silent overwrites. Names that would land on the same file (home / home.png, Home.png / home.png) get a (2) suffix. The output directory must be empty or not exist yet.
• Downloads are bounded and retried. They run eight at a time and retry 5xx, 429 and network errors up to three times. The first file that really fails cancels the others, and the command finishes only once they've all stopped.

Also:

• The build and diff fetch helpers move unchanged from build snapshots to lib/build.ts.
• The argos-cli skill lists the new commands and which token each needs.

Type of changes

enhancement

Checklist

• I have read the CONTRIBUTING doc
• The commits message follows the Conventional Commits' policy
• Lint and unit tests pass locally
• I have added tests if needed

Optional checks:

• My changes requires a change to the documentation
• I have updated the documentation accordingly: the argos-cli skill is updated, but the CLI reference on argos-ci.com still needs the new commands

Further comments

What was tested locally:

• Checks: types, lint and format pass. All 149 unit tests pass, including new ones for path sanitizing, name collisions, the empty-directory guard, retries, cancellation and the baseline page walk.
• Live runs against argos-ci/argos-javascript, using a personal argos login session:
  • build list with each filter.
  • build download on #44215 (26 Storybook screenshots) and #44213 (nested fixtures, .jpg names kept).
  • The non-empty directory guard.
  • baseline download with a personal token, which gets the hint.

Not run locally: baseline download actually downloading, which needs a project token. e2e/baseline.test.ts covers it in CI. It downloads with each matrix job's argos-cli-e2e-node-<version>-<os> build name, which the upload e2e test also uses on every main run.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
argos-js-sdk-reference	Ready	Preview	Oct 21, 2026 8:08am UTC

[linear-code]

ARG-522