docs: auth status, account update and notifications, patches promote, --channel, api --paginate

[eseidel]

Why

Four CLI changes merged to shorebird main today and ship in the next CLI release, which these pages call 1.6.130. Without this PR, the docs would be wrong once it ships:

• They call shorebird patches promote deprecated, but it's back.
• They list apps with shorebird account apps, which now only points at shorebird apps list.
• They don't cover the new commands: auth status, auth token, account update and account notifications.
• They don't mention shorebird api GET /path or --paginate.

CLI PRs: shorebirdtech/shorebird#4110 (promote, --channel), #4111 (api method and --paginate), #4112 (bare account, credential line, auth status, auth token), #4114 (account update, account notifications, account apps redirect).

Changes

• account/cli.mdx:
  • New "Check which credential is active" (auth status) and "Print an access token" (auth token) sections.
  • Current account uses bare shorebird account, and its output adds the Credential line.
  • New "Change your display name" and "Turn email notifications on or off" sections.
  • List apps uses shorebird apps list, with a note on what account apps does now.
• account/api.mdx: the method before the endpoint, and --paginate. The manual paging script stays for older CLIs.
• code-push/patch.mdx, code-push/tracks.mdx:
  • Promote with shorebird patches promote, with set-track --track stable for older CLIs.
  • Removes the deprecation note.
  • Notes --channel as another name for --track.
• code-push/ci/scripting.mdx: the JSON commands table gains account update and notifications, auth status and token, and patches promote, and drops account apps.
• Six changelog entries, one per change. patches-promote-hidden.md stays as history.

The changelog entries use version 1.6.130 and date 2026-10-19, the planned release day in shorebirdtech/shorebird#4108. If it ships on another date or under another version, those two fields need updating before this lands. Hidden aliases (whoami, patches stats, print-access-token, auth login/logout) aren't documented.

Testing

prettier --check ., cspell, Vale and the component label lint pass. npm run build succeeds.

Landing

After CLI 1.6.130 is published (shorebirdtech/shorebird#4108 merged and stable moved), with the dates matching the actual release day.

[eseidel]

Adversarial review

I checked this against shorebirdtech/shorebird main at 1f669f4 (#4110, #4111, #4112, #4113 and #4114 merged) and the 1.6.130 release notes in #4108. Commands, flags, output samples, credential order, Expires behavior, the account apps redirect (exit 64), the --channel aliases (patch, preview, set-track, promote), the --paginate merge and failure behavior, changelog frontmatter, and every docLink and in-page anchor all match. The issues:

Blockers

• code-push/patch.mdx (Promote a patch) and code-push/tracks.mdx (Via the CLI): "promote ... needs Shorebird 1.6.130 or newer. On an older CLI, use set-track" is wrong. shorebird patches promote --release-version 1.0.0+1 --patch-number 1 has worked with exactly these flags since at least v1.6.90. Through v1.6.129 it was hidden and printed a deprecation warning, but it ran. Only the options it inherits from set-track are new in 1.6.130: --track/--channel, --app-id and --json. In patch.mdx this sends older-CLI users to set-track, which needs 1.6.128, and then to "Set patch track for older CLIs", when the command already shown works for them. Suggested fix: "Older CLIs run the same command but print a deprecation warning. --track, --app-id and --json on promote need 1.6.130 or newer." Then drop the set-track --track stable fallback block and the "That form needs 1.6.128" paragraph from patch.mdx, and the "On an older CLI, run set-track" sentence from tracks.mdx.

Should-fix

• shorebird invitations list | accept | decline (#4113) also ships in 1.6.130 (it is the first item in #4108's release notes) but isn't covered. It has no section in account/cli.mdx, no changelog entry and no row in the --json table in code-push/ci/scripting.mdx. The PR body says "four CLI changes" and doesn't say it's deferred. Either add it here or say in the body which PR covers it.
• account/api.mdx: "Without one, the request is a GET, or a POST when you pass fields with -f or -F". The next example, shorebird api /apps -f per_page=100 --paginate, passes -f with no method, so by that rule it's a POST, which --paginate doesn't allow. The CLI keeps the default GET when --paginate is set (methodDefaulted && !paginate in api_command.dart), so the example works, but the page never says so. Add something like "With --paginate the request stays a GET, so -f fields go in the query string." (--input also switches the default to POST, but leaving that to --help is fine.)
• src/content/changelog/api-method-and-paginate.md: "Passing a different method in -X is a usage error." reads as "a method other than those six in -X is an error". That's false: -X takes any method. The error only happens when a method before the endpoint and -X are both given and don't match. Suggested: "Giving a method both before the endpoint and in -X, with different values, is a usage error."
• account/cli.mdx, "Account management commands" intro: it still says the subcommands "inspect your account details, apps, and organizations". After this PR, account no longer lists apps, and update and notifications change settings rather than inspect them.

Nits

• account/cli.mdx, Print an access token: "The token expires soon after you get it" is stronger than the CLI. auth token refreshes only an already-expired token and otherwise prints it as is, so it may expire soon (the CLI help says "may expire soon after"). Suggested: "It may expire soon after you get it, so run shorebird auth token each time rather than storing the output."
• account/cli.mdx: "needs Shorebird 1.6.130 or newer" now appears four times on one page (auth, bare account, update/notifications, account apps). One note under each H2 would do.
• code-push/tracks.mdx, Via the CLI: the existing note about set-track's --release-version/--patch-number (1.6.128) now sits directly above a promote example. Move it next to the set-track --track beta example it refers to.
• account/cli.mdx, "Change your display name": a bare code block with no lead-in sentence, unlike every other section on the page.

[eseidel]

Replies to the adversarial review:

Blocker: promote doesn't need 1.6.130. Fixed in patch.mdx and tracks.mdx. Checked against v1.6.129: promote --release-version --patch-number runs there, hidden and with a deprecation warning. The pages now say older CLIs run it with a warning, and that only --track, --channel, --app-id and --json need 1.6.130. The set-track alternative for older CLIs is gone from patch.mdx.

Should-fix

• Invitations not covered: they're in their own PR, docs: see and answer invitations from the CLI #737.
• -f with --paginate and no method: api.mdx now says --paginate always sends a GET, so the fields go in the query string.
• -X wording in the changelog: it now says that if you also pass -X, it must name the same method.
• "Account management commands" intro: rewritten. account shows who you're signed in as, and its subcommands list organizations and change settings.

Nits

• "expires soon": now "may expire soon".
• Repeated "needs 1.6.130": kept on purpose. Each section is a link target, and readers land on it directly, so the note stays with the command it applies to.
• set-track 1.6.128 note placement in tracks.mdx: moved below the set-track example.
• Display name lead-in: added.

[eseidel]

I'm not sure if you want the change log split out so much. I leave this to you @AbhishekDoshi26. You're welcome to directly make changes and land.

[eseidel]

lgtm

[eseidel]

Holding this until CLI 1.6.130 is published. The prep PR (shorebirdtech/shorebird#4108) has merged, but the tag and stable push won't happen before Monday 2026-10-19. When it ships I'll set the changelog dates to the real release day and land this.

[eseidel]

Shorebird 1.6.130 shipped on October 17 (https://github.com/shorebirdtech/shorebird/releases/tag/v1.6.130), so I've set the changelog dates to 2026-10-17. This is ready to land once approved.

[eseidel]

Landed with --admin: this repo requires an approving review and the review bot doesn't run here. The adversarial review was posted and answered, Eric LGTM'd, and CI was green at b26e18b. @AbhishekDoshi26, if you'd rather fold the six changelog entries into fewer, a follow-up PR can do that.