Support user token auth for non-deploy commands in CI/CD environments

[ram02z]

Summary

Support a documented way to provide a user access token non-interactively in CI/CD environments for commands that require user-token permissions, such as environment-variable management.

Deploy tokens are intentionally distinct from user access tokens and work for fastapi deploy, but non-deploy commands such as fastapi cloud env set require user-token permissions. Today, those commands only read the user access token from the CLI auth file created by fastapi cloud login, which is not practical for CI/CD.

Use case

A GitHub Actions deployment workflow needs to set a non-secret environment variable before deploying:

API_VERSION="$(uv version --short)-${GITHUB_SHA::7}"
fastapi cloud env set API_VERSION "$API_VERSION"
fastapi deploy

fastapi deploy can use FASTAPI_CLOUD_TOKEN, but fastapi cloud env set needs user-token permissions and has no clear non-interactive user-token auth mechanism for CI.

Current behavior

Running this in CI with FASTAPI_CLOUD_TOKEN and FASTAPI_CLOUD_APP_ID set:

fastapi cloud env set API_VERSION "0.1.0-abcdef0"

produces:

✗ error: No credentials found.

hint: Run `fastapi cloud login` or set FASTAPI_CLOUD_TOKEN.

Trying to call the environment-variable endpoint directly with the deploy token also fails, which is expected if deploy tokens are scoped only to deployment operations:

curl --fail-with-body \
  --request POST \
  --url "https://api.fastapicloud.com/api/v1/apps/${FASTAPI_CLOUD_APP_ID}/environment-variables/" \
  --header "Authorization: Bearer ${FASTAPI_CLOUD_TOKEN}" \
  --header "Content-Type: application/json" \
  --data "{"name":"API_VERSION","value":"0.1.0-abcdef0","is_secret":false}"

returns:

curl: (22) The requested URL returned error: 401
{"detail":"Invalid credentials"}

Source inspection

From the CLI source:

• fastapi deploy checks Identity.has_deploy_token() and creates APIClient(use_deploy_token=True).
• APIClient(use_deploy_token=True) reads FASTAPI_CLOUD_TOKEN and sends it as Authorization: Bearer <token>.
• fastapi cloud env set checks identity.is_logged_in() and creates APIClient() without deploy-token mode.
• APIClient() reads the user access token from the CLI auth file and sends it as Authorization: Bearer <token>.

The missing piece is not deploy-token support for env set; it is a supported CI/CD path for commands that need a user access token.

Requested behavior

Please add and document a CI/CD-friendly way to authenticate non-deploy commands with a user access token, for example one of:

1. An environment variable such as FASTAPI_CLOUD_USER_TOKEN that Identity can read for commands requiring user auth.
2. A CLI option such as --token or --user-token for commands requiring user auth.
3. A supported command to write/import a user token into the CLI auth file non-interactively.

It would also help if command errors distinguished these auth modes explicitly:

• fastapi deploy: accepts deploy token via FASTAPI_CLOUD_TOKEN.
• Non-deploy commands requiring account permissions: require user access token / login, not deploy token.

Versions

Observed with fastapi-cloud-cli==0.22.2. Source inspection suggests 0.23.0 has the same env set behavior.