Authentication

Some CLI commands (upload, download, access, list tests) require authentication. Each authentication method also determines what you’re authorized to do.

The CLI resolves credentials in the following priority order:

Priority	Method	Best for	Access scope
1	Access Token	Non-GitHub CI providers	Read & upload for one project
2	Device OAuth	Local development	Same as the logged-in user
3	GitHub OIDC	GitHub Actions — no secrets to manage	Read & upload for one project

Access Token

Pass a token explicitly via --access-token flag or the FLAKINESS_ACCESS_TOKEN environment variable.

# Via flag
flakiness upload ./flakiness-report --access-token <token>

# Via environment variable
export FLAKINESS_ACCESS_TOKEN=<token>
flakiness upload ./flakiness-report

An access token grants read and upload access to a single project. This is the best option for non-GitHub CI providers (GitLab CI, CircleCI, Jenkins, etc.) where OIDC is not available.

Tip

You can find your project’s access token in the project settings on Flakiness.io. Each token is scoped to one project and allows reading test data and uploading reports.

Device OAuth

Log in interactively from your terminal. The CLI opens your browser for authorization and stores the session locally.

flakiness auth login

Device OAuth grants the same access as your user account — all projects and organizations you have access to on Flakiness.io.

Sessions are stored in the platform-specific config directory:

• macOS: ~/Library/Application Support/flakiness/config.json
• Linux: ~/.config/flakiness/config.json
• Windows: ~/AppData/Roaming/flakiness/config.json

This is the best option for local development.

GitHub OIDC

When running inside GitHub Actions with id-token: write permission, the CLI authenticates automatically — no secrets to create or rotate.

permissions:
  id-token: write

steps:
  - run: flakiness upload ./flakiness-report --project myorg/myproject

--project (or FLAKINESS_PROJECT) is required for OIDC authentication. Like an access token, GitHub OIDC grants read and upload access to the specified project.

Tip

GitHub OIDC is the recommended method for GitHub Actions — no secrets to create or rotate. See the GitHub Actions guide for full setup instructions.

Auth Commands

auth login

Log in to Flakiness.io via Device OAuth. Opens your browser for authorization.

flakiness auth login

Options:

• -e, --endpoint <url> — Service endpoint (default: https://flakiness.io, env: FLAKINESS_ENDPOINT)

auth logout

Log out from the current session.

flakiness auth logout

auth whoami

Show the currently logged-in user. Exits with code 1 if not logged in.

flakiness auth whoami