Account CLI Reference

The Shorebird CLI provides several commands to help you manage your authentication state, inspect your account details, and manage your apps and organizations directly from the terminal.

Authentication commands

shorebird auth needs Shorebird 1.6.130 or newer, and shorebird logout --all needs 1.6.135 or newer.

To authenticate with Shorebird on your machine, run:

shorebird login

This command opens your browser to complete the OAuth login process. It also prints the login URL, in case the browser doesn’t open. Once authenticated, your session credentials are saved securely on your machine, allowing you to use shorebird commands without needing to re-authenticate.

When no browser can open on your machine, such as over SSH, in CI, or on Linux without a display, shorebird login instead shows a URL and a code. Visit the URL in a browser on any device and enter the code. To use a code even when a browser is available, run:

shorebird login --device

Logout

To log out of the current Shorebird user session and remove stored credentials from your machine, run:

shorebird logout

To also sign out every other place you’re signed in, such as other machines and browsers, run:

shorebird logout --all

This logs you out here, then opens the Account page in the Shorebird console, where you sign out your other sessions; see Commands that finish in the console. API keys stay valid; revoke them on the console’s API keys page, which shorebird tokens delete opens.

Check which credential is active

The CLI signs in with the first credential it finds: an API key in SHOREBIRD_TOKEN, then GitHub Actions OIDC, then your shorebird login. To see which one it’s using and who it acts as, run:

shorebird auth status

Example output:

Credential:  Login (shorebird login)
Acting as:   user@example.com (ID 42)
Expires:     2026-10-17T01:00:00.000Z

Expires is when the current access token expires. A login and GitHub Actions OIDC get a new token automatically. An API key has no access token to expire, so that line is left out. A personal API key and a service account key both show as API key (SHOREBIRD_TOKEN); the Acting as line tells them apart.

Print an access token

To call the Shorebird API from another tool with your current credentials, print the access token the CLI would send:

curl -H "Authorization: Bearer $(shorebird auth token)" \
  https://api.shorebird.dev/api/v1/users/me

The token may expire soon after you get it, so run shorebird auth token each time rather than storing the output. With an API key in SHOREBIRD_TOKEN, it prints the key. Treat the output as a secret.

Account management commands

The shorebird account command shows who you’re signed in as, and its subcommands manage your account: its settings, sessions, and deletion.

Bare shorebird account, account update, account notifications, and shorebird invitations need Shorebird 1.6.130 or newer. shorebird tokens, account sessions, and account delete need 1.6.135 or newer.

Current account

To see the currently authenticated user’s details, run:

shorebird account

Example output:

ID:             42
Email:          user@example.com
Display name:   Example User
Plan:           pro
Overage limit:  10000
Credential:     Login (shorebird login)

This command is useful for verifying which account you are logged into and checking your plan level and your patch overage limit. Credential is how the command signed in; see Check which credential is active.

shorebird account whoami prints the same thing.

To change your account’s email or sign-in method, see Account access and ownership.

Change your display name

To change the name on your account, run:

shorebird account update --name "Jane Doe"

Turn email notifications on or off

The emails this setting controls warn you when an app is near or over its plan’s patch install limit. At the limit, patches stop installing on devices (see Patches stopped installing on devices). To see whether these emails are on, run:

shorebird account notifications

To turn them off, or back on:

shorebird account notifications --email off
shorebird account notifications --email on

In the console, the same switch is Usage alerts under Email notifications on your Account page. Each of these emails also has an unsubscribe link that turns them off without signing in. Emails about invoices, payments, invitations and account security are always sent.

API keys and sessions

To list your API keys (ID, name, and when each was created, last used, and expires) or the sessions signed in to your account, run:

shorebird tokens list
shorebird account sessions

shorebird tokens on its own does the same as tokens list, and shorebird api-keys and shorebird token are the same as shorebird tokens. Neither command ever prints a key. Both read the lists only when you’re signed in with shorebird login; with an API key or GitHub Actions OIDC, they open the console page instead.

Creating and deleting API keys and signing out sessions happen in the Shorebird console, where a person confirms them. shorebird tokens create and shorebird tokens delete (or tokens revoke) open the API keys page, and the Account page signs out your sessions. To sign out everywhere at once, run shorebird logout --all. For CI, create a service account key rather than a personal API key.

Delete your account

shorebird account delete

This opens the Account page in the Shorebird console, where you delete your account. Deleting an account can’t be undone; see Delete an account first.

See Commands that finish in the console for how it behaves in CI and with --json.

List apps

To list all the Shorebird apps that your current account has access to, run:

shorebird apps list

On Shorebird 1.6.129 and older, shorebird account apps prints the same list. From 1.6.130 it prints the shorebird apps list command instead and exits with an error.

Example output:

01H...  Acme Mobile  1.2.3  4
01J...  Acme Internal  -  -

The output displays the App ID, display name, latest release version, and latest patch number (with - indicating no release or patch has been published yet).

Answer invitations

shorebird invitations list, accept and decline show and answer the organization and app invitations sent to you. See Accept an invitation.

App management commands

As of Shorebird 1.6.121, the shorebird apps commands list, rename, and transfer your apps. In 1.6.135 and newer, shorebird apps delete sends you to the console to delete one. shorebird apps list is covered under List apps.

rename, delete, and transfer act on the app in shorebird.yaml in the current directory. Pass --app-id to pick a different app or to run the command from outside a Shorebird project. If your app uses flavors, pass --flavor to pick that flavor’s app ID.

Rename an app

To change an app’s display name, which can be up to 128 characters, run:

shorebird apps rename --name "Acme Consumer"

Example output:

Renamed "Acme Mobile" to "Acme Consumer".

Transfer an app

To move an app into another organization, pass the organization’s ID. Run shorebird orgs list to find it:

shorebird apps transfer --org-id 42

Example output:

Moved "Acme Mobile" into "Acme Corp".

You must be a member of the target organization, and have permission to move apps out of the app’s current organization and into the target one. See Organizations for more on transferring apps.

Delete an app

Deleting an app permanently deletes every release and patch that belongs to it, and can’t be undone. Read Delete Apps, Releases, and Patches before you do this.

shorebird apps delete doesn’t delete the app; you delete it in the Shorebird console, where you confirm in person. Run:

shorebird apps delete

It prints the link to the app’s Settings page in the console and opens it in your browser when your machine can. Delete the app from the Danger zone there.

Without a terminal, in CI, or with --json, nothing is deleted; see Commands that finish in the console.

Before 1.6.135, apps delete deleted the app from the CLI: 1.6.129 to 1.6.134 after you type its display name or pass it with --confirm-name, and 1.6.121 to 1.6.128 always with --confirm-name.

Organization commands

shorebird orgs lists, shows, creates, and renames your organizations, and shorebird usage shows an organization’s patch installs. shorebird members, shorebird service-accounts, and shorebird audit-log manage what’s in an organization. All of them need Shorebird 1.6.135 or newer. shorebird org, shorebird organizations, and shorebird teams are the same as shorebird orgs.

The commands that act on one organization pick it with --org-id, or, for orgs get, orgs update, and usage, with its ID as their argument. Without either, they use the organization that owns the app in shorebird.yaml in the current directory, or your only organization.

List organizations

To list the organizations you can access, run shorebird orgs list, or shorebird orgs on its own:

shorebird orgs list

Example output:

1  Acme Corp  team  admin
2  user@example.com  team  owner

This output displays the Organization ID, name, organization type (always team), and your role (owner, admin, appManager, developer, or viewer). An organization you are not a member of, but where you collaborate on one of its apps, shows the role none.

Before 1.6.135, shorebird account orgs printed this list. It still works, and says it is now shorebird orgs list.

Show, create, and rename an organization

# An organization, your role in it, and its patch installs
shorebird orgs get 42

# A new organization, with you as its owner
shorebird orgs create "Acme Corp"

# Rename an organization
shorebird orgs update 42 --name "Acme Inc"

Your first organization is free. Once you own one, creating another needs a paid plan of your own, or your enterprise’s when your enterprise manages your account. See Creating an organization. Create one with a shorebird login session or a full-access personal API key; a release and patch only key and a service account can’t. Renaming needs the Admin or Owner role.

Patch install usage

To see how many patch installs the organization’s plan has used this period, and which apps used them, run:

shorebird usage 42

The total covers every organization billed on the same plan, such as the owner’s other organizations, or an enterprise’s organizations when the enterprise is billed for them. The app list is narrower: the owner sees the apps they own, and other members see this organization’s apps, so it can add up to less than the total. An Auditor service account, someone who only collaborates on one of the organization’s apps, and a release and patch only key can’t see usage, and orgs get leaves it out for them.

Members, service accounts, and the audit log

shorebird members lists, invites, and removes the organization’s members, and changes their roles. See Manage members from the CLI.
shorebird service-accounts creates, changes, and deletes the organization’s service accounts, and manages their keys and trust rules. See Manage service accounts from the CLI.
shorebird audit-log reads and exports the organization’s audit log. See Read it with shorebird audit-log.

Run shorebird orgs <command> --help or shorebird usage --help for options and an example --json run.

Metrics commands

shorebird metrics shows the same install, adoption, and usage numbers as the Insights tab in the Shorebird console, for the app in shorebird.yaml or the one you pass with --app-id. Use it to check how a patch is rolling out without opening the console, or to feed the numbers into a script with --json. It needs Shorebird 1.6.129 or newer.

shorebird metrics adoption --release-version 1.0.0+1

Run shorebird metrics --help to see every metric, and shorebird metrics <metric> --help for its options.

Commands that finish in the console

Actions that are hard to undo or that create credentials are finished by a person in the Shorebird console. These commands don’t perform them: they print a link to the console page that does, and open it in your browser when your machine can.

shorebird logout --all, after logging you out on this machine
shorebird tokens create and shorebird tokens delete
shorebird account delete
shorebird apps delete
shorebird service-accounts keys create
shorebird enterprise members remove (1.6.136 or newer)

shorebird tokens list and shorebird account sessions open the console too when you aren’t signed in with shorebird login.

Without a terminal, in CI, or with --json, no one is there to finish the action, so the command doesn’t perform it and exits with code 69 and a console_required error. logout --all has still logged you out on this machine. The error’s hint holds the console link. Scripts can check for that code and pass the link to a person.

These commands need Shorebird 1.6.135 or newer.

JSON output for automation

The shorebird account, shorebird apps, shorebird orgs, and shorebird usage commands support the --json flag, making them easy to integrate into scripts and automation workflows. shorebird account delete and shorebird apps delete open the console instead, so with --json they never delete anything: they exit with a console_required error, or with an ordinary error first, such as when apps delete can’t find the app.

shorebird account whoami --json
shorebird orgs list --json
shorebird apps list --json

When using --json, the CLI will output a structured JSON response instead of human-readable text.