Argos Upload

Argos media upload

argos media upload <files...> uploads standalone images and videos — not tied to a build or a test run — and prints a share URL and a Markdown embed for each.

argos media upload checkout-before.png checkout-after.png --branch feat/checkout

Run argos media --help for exact flags. This skill covers the parts --help cannot: when to upload, how the result reaches a human, and how to read back what they say about it.

When to upload

Upload when a change is visual and a human has to see it to judge it:

• You changed UI and are working on a branch or a pull request. A before/after pair saves the reviewer from checking out your branch.
• You recorded a Playwright video or a screen recording of a bug reproduction.
• You are reporting a rendering problem that a code snippet cannot convey.

Do not upload when text does the job. A stack trace, a diff, a log excerpt and a list of failing test names are all better as text: searchable, quotable, and readable in a terminal. An unnecessary screenshot is noise in the review.

Do not upload build screenshots that Argos already has. If a visual test run produced them, they are already in the build and linked from the pull request — use argos build snapshots instead.

Getting it into a pull request

Name where the media belongs and Argos does the posting. It keeps one comment per pull request listing every media attached to it, edited in place rather than appended to.

argos media upload after.png --pr 1234              # the pull request exists
argos media upload after.png --branch feat/checkout # it does not, yet

--branch is the one to reach for while working. The media is staged: it has its share URL immediately, and the moment a pull request opens for that branch Argos attaches it and posts the comment on its own. You do not have to come back and connect the two. --pr publishes straight away.

Passing neither uploads a loose media: a share URL and nothing else. That is the right call for a chat message or an issue, where you paste the Markdown yourself. Neither flag is inferred from the environment, CI included — an upload does not post to a pull request unless you asked it to. Two consequences worth knowing before you leave them off: nothing will ever attach that media to a pull request, and since a loose media's identity is only its name, uploading shot.png from two different branches makes them versions of one media rather than two.

Commenting needs the project connected to GitHub, and pull request comments enabled on it (argos project get). Without that the upload still succeeds and you paste the Markdown yourself.

Two things --branch will not do: publish to a pull request opened from a fork (a fork's branch name is chosen by an outsider, so Argos never matches staged media against it), and publish anything whose bytes never landed.

Embedding the result

The command prints, per file:

checkout.png (after)
  ID: 4821
  staged on feat/checkout
  image/webp · 184 KB · 1440x900 · public · ready
  URL: https://app.argos-ci.com/m/kQ8vN2pXr4tYw7...
  File: https://media.argos-ci.com/media/12/a1b2c3.webp
  Markdown: ![checkout.png](https://app.argos-ci.com/m/kQ8vN2pXr4tYw7...)

Paste the Markdown line verbatim. Do not hand-write the embed:

• For an image, the Markdown is a plain ![alt](url).
• For a video, it is the poster frame wrapped in a link to the share page. GitHub renders an inline player only for media it hosts itself, so a <video> tag or a bare .mp4 link pointing at Argos renders as a dead link. The poster-in-a-link is the form that actually shows something.

URL is the share page, for a human. File is the image or video itself, for you: fetch it when you want to look at what you just uploaded. Use --json when you parse the output.

Before/after pairs

A file name ending in -before or -after is read as a label, not as part of the name: checkout-before.png and checkout-after.png both upload as checkout.png, one as each half of a pair, and the pull request comment shows them side by side for comparison. That is the whole reason to name them that way.

argos media upload checkout-before.png checkout-after.png --branch feat/checkout

--state before|after sets it explicitly, for files that are not named that way. It applies to every file in the command, so do not pass it to a pair — both halves would land on the same name and state, and the second would replace the first. The CLI refuses that rather than doing it.

--description "<prose>" adds a line under the media in the comment. Use it to say what the reviewer is looking at when the image does not speak for itself.

Re-uploading: versions, and one stable link

Uploading the same name again on the same branch or pull request adds a version rather than creating a second media. The share URL does not change and always shows the newest version, so Markdown already posted to a pull request picks up the new image with nothing to edit — re-run your command after a fix and the review updates itself.

Byte-identical bytes are not a new version, and cost nothing: Argos recognizes the file and skips both the transfer and the meter.

A media's name and branch are its identity, so they are fixed once it is published. While it is still staged you can correct them:

argos media update 4821 --name checkout.png --branch feat/checkout
argos media update 4821 --no-branch          # detach: nothing will publish it

Reading the feedback you were given

A human can comment on an uploaded screenshot and pin a comment to a spot on it. That is how you get told "this button is misaligned" about a pixel you cannot look at. Find the media, then read its threads:

argos media list --branch feat/checkout --json      # or --pr 1234
argos media comment list 4821 --json                # open threads; --all for settled ones

media comment list shows open threads only, so what comes back is what is left to do. Add --all to see the ones already dealt with.

Each comment carries the pin as Pinned: point x,y in normalized 0–1 coordinates of the image (0.62,0.34 is 62% across, 34% down), and the media's File: URL is what you fetch to go and look. A comment also carries the media version it was written against: if versionCount is above 1, the pin describes the bytes of that upload, so resolve it before trusting the coordinates.

argos media versions 4821 --json   # match the comment's media version ID, use its file

Then close the loop on each thread:

argos media comment create 4821 --reply-to <threadId> --body "Fixed in abc1234."
argos media comment resolve 4821 <threadId>

Resolve only what you actually fixed. Resolving something you skipped is how feedback gets silently dropped — reply explaining why instead, and leave it open.

Compression

Images are converted to WebP before upload, which is where the speed comes from: a 1440x900 PNG screenshot goes from ~1 MB to well under 100 KB. The media keeps the name you gave it (checkout.png), because that name is its identity and must not move when Argos changes how it compresses.

Argos leaves a file alone when converting would not help — a video, an already-efficient WebP or AVIF, an animated GIF, an image too large for the WebP encoder (over 16383px on a side, which a long full-page capture reaches), or bytes that came out no smaller. --no-compress uploads exactly what you have.

One consequence worth knowing: converting drops the file's metadata, so a photo's EXIF — including GPS, if the camera recorded it — does not reach Argos. With --no-compress, or for a format that is left alone, it does.

Visibility, and what it does not cover

--visibility controls the share page — team requires an Argos session, public does not. It defaults to the project's visibility in Argos: public for a public project, team for a private one. So the usual upload needs no flag at all. team is Pro-only; on the free plan every share page is public, and asking for team is rejected rather than silently downgraded.

Re-uploading does not revisit this. A media keeps the visibility it was created with unless a later upload passes --visibility explicitly, so a screenshot deliberately kept team-only stays that way.

It does not protect the file: media files are always reachable at an unguessable CDN URL, because GitHub fetches embedded images server-side with no session and could not render them otherwise.

So treat an uploaded file as "anyone with the link". If a screenshot must never be reachable by someone who obtains its URL, don't upload it — say so instead of uploading it anyway.

Authentication

Media belongs to a project, so it inherits that project's access — including transferring with it. With a personal access token, pass --project <owner/project> (or set ARGOS_PROJECT); a project token already identifies its own project.

Every media comment command needs a personal access token, reading included: a project token can list the media a review is about but not the review itself.

What it costs

Uploads draw on the same screenshot allowance as visual tests — there is no separate quota to track. One image is 1 screenshot; one video is 25, because it costs more to store and serve. Uploading the same file twice is free.

Files are kept 30 days on the free plan and a year on Pro, then deleted, per version — the plan decides it, there is nothing to pass. An expired link renders an "unavailable" page, so a pull request embed degrades visibly rather than into a broken image.

Limits worth knowing before you upload

• Accepted formats — PNG, JPEG, WebP, AVIF, GIF, MP4, WebM, MOV. Anything else is refused before the upload starts.
• Size — 50 MB on the free plan, 500 MB on Pro. A long screen recording is the usual thing that trips this; trim it before uploading.
• Video codecs — Argos does not transcode. Most MP4/WebM plays fine, as does the H.264 that screen recorders produce; ProRes and some HEVC exports won't play inline and the viewer gets a download. Export to H.264 if you need playback.
• Comment size — the managed pull request comment lists up to 20 media.
• No waiting — a media is fully usable the moment the upload finishes. The poster frame is derived by the CDN on request, so a video's Markdown embed is correct immediately.