Authenticate

ShipEasy uses an OAuth-style PKCE device-auth flow. Run one command, click one link in your browser, and the CLI plus every MCP tool on your machine is signed in. There is no API key to copy, paste, or rotate — for interactive use.

For CI, you swap the device-auth flow for a long-lived SHIPEASY_API_TOKEN env var. Same code paths underneath; different credential source.

Log in

Your browser opens to a confirmation page. Sign in with GitHub, Google, or a magic link. When you confirm, the CLI command exits with success and the credentials are saved to ~/.shipeasy/credentials (mode 0600).

Under the hood — device-auth flow

There is no plaintext password anywhere on disk. PKCE means an attacker who steals the URL still can't complete the flow without your verifier.

Pick a project

If your account has access to more than one project, the login flow lets you choose one. To switch later:

shipeasy whoami            # show the active project
shipeasy projects list     # list every project you can access
shipeasy projects use acme # set the active project

You can also override the project on a per-command basis:

shipeasy --project acme flags list
SHIPEASY_PROJECT=acme shipeasy flags list

The order of precedence is: --project flag > SHIPEASY_PROJECT env > ~/.shipeasy/credentials > nothing (the CLI errors out).

Multiple orgs

Each ShipEasy project belongs to one org. If you're in several orgs, projects from all of them show up in shipeasy projects list. There is no separate org switch — the project is the authoritative scope and the org is implied by the project ID.

Log out

shipeasy logout

This wipes ~/.shipeasy/credentials. You'll need to login again before the next CLI or MCP call.

To revoke the server-side session (e.g. you suspect the credential file leaked), use shipeasy logout --revoke. This calls the admin API to invalidate the refresh token before deleting the local file. After this, even an attacker with the credential file can't obtain new access tokens.

Token rotation

Refresh tokens rotate on every use. The pattern is:

1. CLI sees the access token is expired (or about to be).
2. CLI calls POST /auth/device/refresh with the current refresh token.
3. The server returns a new access token and a new refresh token, and invalidates the old refresh token.
4. The CLI writes the new pair to disk before doing anything else.

This means a stolen refresh token is good for at most one refresh — the moment you next use the CLI on your laptop, the attacker's copy stops working.

Using ShipEasy in CI

For GitHub Actions, GitLab CI, and any non-interactive environment, generate a long-lived API token in Project → Tokens → Create and pass it as SHIPEASY_API_TOKEN:

- name: Validate i18n keys
  env:
    SHIPEASY_API_TOKEN: ${{ secrets.SHIPEASY_API_TOKEN }}
  run: shipeasy i18n validate --profile en:prod

API tokens skip the device-auth flow entirely. They're scoped to one project, can be marked read-only or read-write, and can be revoked with one click.

SDK keys vs API tokens — pick the right one

A common mistake is to use an API token in the SDK at runtime. Don't — they're much more powerful than they need to be, and they don't enforce per-domain rate limits. Use SDK keys for the SDK, API tokens for everything else.

What gets stored on your machine

~/.shipeasy/credentials   # mode 0600, JSON
├─ access_token           # short-lived (1h), refreshed automatically
├─ refresh_token          # long-lived, rotates on every use
├─ project_id             # active project
├─ user_email             # for `whoami`
└─ created_at             # when this credential set was issued

The credentials file is the only state the CLI writes. Project/env preferences live alongside in ~/.shipeasy/config.json. Neither file should ever be committed.

Troubleshooting