[gregberge]

Important

Needs argos-ci/argos#2747 deployed before release. Until then the token commands answer 404. The project field is harmless on today's API, which strips unknown fields, but it does nothing.

Description

argos-ci/argos#2747 replaces the single projects.token with project tokens. A token can be linked to several projects, carries permissions and can expire. This PR makes the SDK and the CLI work with them.

Name the project on the CI endpoints

A token linked to several projects does not identify a project by itself, so the API answers 400 unless the request names one. When ARGOS_PROJECT (or the project option) is set, @argos-ci/core now sends it as project to:

• GET /project (query)
• POST /builds, POST /builds/finalize, POST /baseline, POST /deployments (body)

POST /media already took it. When project is unset, nothing is sent, so single-project tokens behave exactly as today.

• finalize() and deploy() gain a project parameter, like upload(). skip() accepts one too.
• argos finalize, skip, deploy and baseline download take --project.
• @argos-ci/gitlab reads ARGOS_PROJECT for its GET /project.

Behaviour change: a token linked to one project used to ignore an ARGOS_PROJECT that named some other project. Now the API rejects it with a 401 (This project token does not have access to the project "…").

Rotate tokens from the CLI

argos project token list    [--project owner/project]
argos project token create  --name <name> [--permissions <p…>] [--expire-at <iso> | --expires-in <days>]
argos project token revoke  <tokenId>

argos account project-token list|revoke
argos account project-token create --projects web docs --name <name> […]

• The project commands use /projects/{owner}/{project}/tokens. The account commands use /accounts/{accountSlug}/project-tokens, the only endpoint that can create a token linked to several projects.
• create prints the token, since the API returns it only once. With --json, the value is in token.
• --permissions and --projects take space-separated values, like upload --files. If --permissions is omitted, the API grants every permission. Commander rejects unknown permissions before the request is sent.
• --expire-at and --expires-in can't be used together. The date must be in the future, and it is sent as UTC ISO, the only format z.iso.datetime() accepts.
• Output follows the existing JSON contract. revoke returns { revoked, tokenId }, like contributor remove. Token names go through sanitizeTerminalText.

API client

packages/api-client/src/schema.ts is regenerated from the #2747 branch with pnpm --filter @argos/backend generate-openapi. Most of the diff is drift that production already serves (capture, Agent, awaitingReviewStatus, analytics storybook…). I checked this by diffing production's openapi.yaml against the PR spec: they differ only in the token changes.

Skills

argos-cli and argos-upload now cover tokens linked to several projects, the 403 for a missing permission, and the rotation flow, which pipes create --json | jq -r .token | gh secret set ARGOS_TOKEN so the value is never echoed.

No changeset files: Lerna versions from the conventional commits.

Tests

• @argos-ci/core: upload, skip, finalize and deploy send project when it is passed or set in ARGOS_PROJECT, and send no field or query param when it is not. The upload test also covers the /baseline lookup.
• @argos-ci/cli: unit tests for expiration handling, the request body and the token formatters.
• Smoke test: I ran the built CLI against a local mock API and checked every new command, plus finalize, skip, deploy and baseline download with and without --project/ARGOS_PROJECT.
• I did not add e2e tests for the token commands: the e2e suite runs against production, which doesn't serve these endpoints yet.

Follow-ups

• argos login does not request the account:admin OAuth scope. The account endpoints require it, so argos account project-token * (like the existing account member|invite|domain commands) works only with a personal access token, not with an argos login session.
• The docs PR docs(tokens): several project tokens per project, shown once docs#273 says baseline download has no --project flag. It now has one, so the CLI reference needs a follow-up there.

Refs ARG-519

🤖 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	Nov 5, 2026 1:46pm UTC

[linear-code]

ARG-519