Skip to content
Shorebird

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

Section titled “Authentication commands”

Login

Section titled “Login”

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

Section titled “Logout”

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

shorebird logout

Check which credential is active

Section titled “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.

Section titled “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.

These auth commands need Shorebird 1.6.130 or newer.

Account management commands

Section titled “Account management commands”

The shorebird account command shows who you’re signed in as, and its subcommands list your organizations and change your account settings.

Current account

Section titled “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. Bare shorebird account and the Credential line need Shorebird 1.6.130 or newer.

Change your display name

Section titled “Change your display name”

To change the name on your account, run:

shorebird account update --name "Jane Doe"

Turn email notifications on or off

Section titled “Turn email notifications on or off”

The emails Shorebird sends today warn you when an app is near or over its plan’s patch install limit. To see whether they’re on, run:

shorebird account notifications

To turn them off, or back on:

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

account update and account notifications need Shorebird 1.6.130 or newer.

List apps

Section titled “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).

List organizations

Section titled “List organizations”

To list the organizations you can access, run:

shorebird account orgs

Example output:

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

This output displays the Organization ID, name, organization type (personal or 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.

Answer invitations

Section titled “Answer invitations”

shorebird invitations list, accept and decline show and answer the organization and app invitations sent to you. See Accept an invitation. They need Shorebird 1.6.130 or newer.

App management commands

Section titled “App management commands”

As of Shorebird 1.6.121, the shorebird apps commands list, rename, delete, and transfer your apps. 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

Section titled “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

Section titled “Transfer an app”

To move an app into another organization, pass the organization’s ID. Run shorebird account orgs 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

Section titled “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.

Before deleting, the command says what goes with the app: its releases and their patches, its channels, and its collaborators. Devices running the app stop getting patches. In a terminal, you then type the app’s display name to confirm:

shorebird apps delete

In scripts and CI, where nothing can prompt, pass the display name with --confirm-name. There is no --yes for deleting an app, so an app is never deleted without naming it:

shorebird apps delete --app-id <app-id> --confirm-name "<display name>"

The prompt needs Shorebird 1.6.129 or newer. Earlier releases don’t prompt and always need --confirm-name.

Metrics commands

Section titled “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.

JSON output for automation

Section titled “JSON output for automation”

All shorebird account and shorebird apps subcommands support the --json flag, making them easy to integrate into scripts and automation workflows.

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

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