Skip to content

Tags

Tags

v4.3.1-canary.44ee998

Toggle v4.3.1-canary.44ee998's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
feat(logs): make clerk logs generally available (#633)

* feat(logs): make clerk logs generally available

Remove the CLERK_EXPERIMENTAL=logs gate so `clerk logs` shows in
`clerk --help` and shell completion and runs without any env var. Add
it to the root README's help output, drop the gate from the logs README,
tests and E2E runs, and drop the "still experimental" sentence from the
unreleased logs changesets. lib/experimental.ts stays for the next gated
command.

Refs CORE-4359.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(logs): keep a poll's fetched logs when the cursor repeats, and state --follow's real late-log limit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

v4.3.0

Toggle v4.3.0's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
ci(repo): version packages (#636)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

v4.2.1-canary.24297c1

Toggle v4.2.1-canary.24297c1's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
docs: document which CLI output is a stable contract (#632)

Add an "Output stability" section to the README: human output can change
in any release, scripts and agents should use --json. Name breaking
--json changes as major in the changeset policy and skill, and say
human-output changes (such as a new table column) are not breaking.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

v4.2.0

Toggle v4.2.0's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
fix(release): retry codesign when Apple's timestamp server fails (#634)

v4.2.1-canary.33ad54a

Toggle v4.2.1-canary.33ad54a's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
feat(logs): add agent-oriented examples to clerk logs help (#626)

* fix(logs): print every clerk logs error as JSON in agent mode

Give the logs errors that had no code one, so agent mode prints them as
the JSON error envelope instead of plain text: bapi_unexpected_response
for a body the CLI can't use or a repeated cursor, and a new
log_types_unavailable for a Backend API without GET /v1/logs/types.
--payload-filter and --fields without --type now point at clerk logs
schema, with examples.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(logs): add agent-oriented examples to clerk logs help

clerk logs --help now walks the discovery flow (schema, a type's
fields, a filtered list, a log group, a follow) and describes the
--json output shapes, --cursor paging and log retention; list, get and
schema gain --json examples of their part of the flow. The logs README
gets the same flow, an output-shape table and the agent-mode errors.
help.test.ts pins clerk logs --help, checks every help and README
example against the command tree, and keeps the README flow equal to
the help's.

Refs CORE-4352

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changeset): add agent-oriented help to clerk logs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(logs): point clerk logs help at a group's events_cursor

`--grouped` added `has_more_events` and `events_cursor` to each flow, and its
human note names `clerk logs get <group_id> --cursor <events_cursor>`, but the
agent-facing help only explained `cursor.next`. An agent reading
`--grouped --json` had no way to learn how to read the rest of a group. The
`clerk logs --help` description, `get`'s `--cursor` option and example, the
README's output table and the changeset now say it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

v4.2.1-canary.410b19f

Toggle v4.2.1-canary.410b19f's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
fix(logs): reject Unix-seconds timestamps in `--from`/`--to` (#617)

* fix(logs): reject Unix-seconds timestamps in `--from`/`--to`

A bare number below 100000000000 (March 1973 in milliseconds) is now a
usage error instead of a January 1970 time. One that reads as Unix
seconds suggests the millisecond value or an ISO 8601 date-time.

Fixes CORE-4361

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(logs): wait longer for the user.created log in the list E2E

The log pipeline has taken over 30s to surface a new user's
user.created log in CI. Poll for up to 60s instead, and raise the
beforeAll timeout to 120s to cover the wait plus user creation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(logs): drop the Unix-seconds error details from the README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(logs): reject any bare number before 2020 in `--from`/`--to`

Replace the seconds-specific and "before March 1973" branches with one
fixed cutoff (2020-01-01T00:00:00Z) and one message. This also catches
millisecond values like 1975 that the old threshold accepted. ISO dates
and date-times before 2020 still parse, since they aren't ambiguous.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

v4.2.1-canary.f4631dc

Toggle v4.2.1-canary.f4631dc's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
feat(logs): add `--follow` to `clerk logs list` (#616)

* feat(logs): add `--follow` to `clerk logs list`

Print the normal backfill oldest first, then poll `GET /v1/logs` every
`--interval` (default 2s) with `event_time_after` set to the newest log
printed, deduping the boundary millisecond by log ID. `--json` streams
NDJSON. Transient failures retry with backoff; Ctrl-C exits 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(logs): look back 10s on each follow poll, exit 130 on Ctrl-C, give up after 5m

Each poll now asks for `event_time_after = newest printed - 10s` (never past
`--since`/`--from` or a `--limit`-cut backfill) and skips logs it already
printed by ID, so a log the pipeline delivers late is still printed once,
after newer ones. IDs older than the window are evicted, so memory stays
bounded.

Ctrl-C is left to the CLI's handler and exits 130 by SIGINT, like
`webhooks listen`. Transient failures give up with the last error after
5 minutes with no successful request.

Also from review: a poll that hits the request cap resumes from its cursor
instead of skipping the rest, pages fetched before a stop are printed, a
page without a `data` array is rejected, and the E2E waits for the first
poll by its page size and checks lines buffered before the user existed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(logs): anchor an empty follow at the API's Date and time out stuck requests

An empty backfill anchored the follow at `searched_to`, which on a first
page is 5 minutes past the API's clock, so the logs of those minutes never
printed. Anchor at the first response's `Date` header instead, falling
back to the local clock read before the request.

Each follow request now gives up after 30 seconds and is retried like a
network error, so a connection that stops answering can't hang the follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(logs): reject a Logs API page whose data holds non-object items

`readLogsPage` now checks that every item of `data` is an object, so a
response like `data: [null]` fails with the usual "The Logs API returned an
unexpected response." error instead of a `TypeError` later on. `list` and
`--follow` share the reader, so both get the check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(logs): cap each --follow poll's lookback at 5 minutes before the API's clock

Each poll's `event_time_after` is now the later of the newest printed
`event_time` minus 10s and the API's clock minus 5 minutes, read from the
latest response's `Date` header (or the local clock read before the request),
and still never before `--since`/`--from` or the `--limit` backfill floor. A
quiet stretch no longer makes every poll rescan everything since the last log,
and the dedupe set is pruned to the same window. A log that takes more than 5
minutes to become visible may be missed; the bound can be tuned once arrival
delay is measured.

The help text, README and changeset now say `--follow` is for live debugging
and point to log drains for exporting or syncing logs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(logs): wait longer for the user.created log in the list E2E

The log pipeline has taken over 30s to surface a new user's
user.created log in CI. Poll for up to 60s instead, and raise the
beforeAll timeout to 120s to cover the wait plus user creation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

v4.2.1-canary.adcf15f

Toggle v4.2.1-canary.adcf15f's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
feat(migrate): make clerk migrate generally available (#594)

* feat(migrate): make clerk migrate generally available

Remove the CLERK_EXPERIMENTAL=migrate gate. `clerk migrate` now registers
like every other command, so it shows in `clerk --help` and completion and
runs without an env var. Drops lib/experimental.ts, the
experiment_disabled error code, the gate test, and the env setup in tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: list clerk migrate in the README and match its help

Add `migrate` to the root README's help output. In the migrate README,
show `export [platform]` and `import [file|export-run-id]` as optional the
way `--help` does, say `sources` takes no `--runs-dir`, match the export
`-y` wording, and restore the libsql token sentence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changeset): Make clerk migrate available without CLERK_EXPERIMENTAL

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changeset): stop calling clerk migrate experimental in the earlier changesets

None of them has shipped, and this slice makes migrate generally available,
so the release notes would have said "still experimental" beside the entry
announcing it. Lands only with the flip.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(migrate): point migration doc links at the per-platform guides

`clerk init`'s auth-library scan and `clerk migrate export workos`
linked to the old `/docs/migrations/*` pages or the migration overview.
They now link to the guide for each platform under
`/docs/guides/development/migrating/`: authjs, auth0, supabase,
firebase, better-auth and workos. Passport.js and Kinde have no built-in
source, so they link to the custom-source guide. URL strings only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(migrate): point the custom-source link at the migration guide

`CUSTOM_SOURCES_URL` linked to the "Custom sources" section of the CLI's
README on GitHub. Errors from a source you wrote, `clerk migrate
sources`, and the `--source` help now link to the custom-source guide
under /docs/guides/development/migrating/, which covers the same
validation errors and hook signatures for someone migrating, not
developing the CLI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(completion): check completion offers migrate and its subcommands

With `gate.test.ts` gone, nothing checked that completion offers
`migrate` or its subcommands. Applies the review's suggested test as
written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changeset): add the Oxford commas to the migrate changesets

Applies the review's suggestion for `migrate.md` ("Better Auth, or
Auth.js"), and the same fix in `migrate-custom-sources.md` ("passwords,
MFA, and metadata").

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): say the CLI redacts a libsql token, in the active voice

Applies the review's suggestion as written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor: keep the CLERK_EXPERIMENTAL gate, and document it

`migrate` was the gate's only user, but it won't be the last command to
ship to `main` before it's ready. This keeps `lib/experimental.ts`, its
test and `ERROR_CODE.EXPERIMENT_DISABLED` in place, with full JSDoc on
`enabledExperiments`, `isExperimentEnabled` and `requireExperiment`. A new
section in `.claude/rules/commands.md` explains how to gate a command and
how to remove the gate when it ships.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): say "auth platform" in the migrate help and README

The help said "another auth provider" for `clerk migrate` and "a source
platform" for `migrate export`, and the README used both. The docs say
"platform" throughout and never "auth provider", and `migrate` already
uses "provider" for OAuth providers, so `clerk migrate` now says "auth
platform" in its help text and README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): add the missing Oxford commas

Adds the comma before the "and" or "or" that ends a list of three or more
items across `clerk migrate`'s README, help text, and code comments: 113
commas in 32 files, with no other wording changed. Log, error, and prompt
strings are left as they are, since tests may assert on them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): say "auth platform" in the --reserve-unverified text

In this CLI a "source" is the mapper `import --source` reads a file with,
but the --reserve-unverified flag help, the unverified-only reject hint,
the prompt, the changeset, and the README said "the source never
verified" for the platform the users come from. They now say "the auth
platform never verified", matching the rest of the help text. Mentions of
a custom source, and "each source declares" in the README, still mean the
mapper and are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): drop the save-location prompt from export clerk's example

`clerk migrate export clerk`'s help example said it prompts for "the
source instance and where to save the file". It never asks where to save:
the file goes to `--output` or the run folder, as the README says. It now
says "Prompts for the instance to export from", which also drops
"source", since a source is the mapper `import --source` reads with.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): say --service-account takes the key's JSON too

`clerk migrate export firebase --service-account` takes a path to the key
file or the key's JSON pasted in whole, but the flag help, the README,
and the agent-mode usage error all said a path. The flag is now
`--service-account <key>`, and all three name both forms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): correct the dry-run exit codes, Firebase key errors, and null spellings

- `--dry-run` also exits 1 on an API, auth, or runtime error, not only 2
  when the run would be refused and 0 otherwise.
- Only a Firebase key with the wrong `type` names the console page. A web
  app config has no `type`, so it fails with `"project_id" is missing`.
- A timestamp verification field also reads `nil` and `undefined` as not
  verified, in any case, and any other value counts as verified.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): name --source in export clerk's comment

The comment said the export feeds `clerk migrate import --transformer
clerk`. The flag is `--source`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): say Firebase phones import verified, and why

Firebase has no phone-verified field: a user confirms a number by SMS,
and an admin vouches for one set through the Admin SDK, as with a phone
an admin adds in Clerk. So every Firebase phone imports verified, and
`--reserve-unverified` never applies to them, but nothing said so. `clerk
migrate sources firebase` now lists it as a caveat, the README and the
changeset say so, and a test pins the behavior. The README also says a
number on the record signs in by SMS when the project has the Phone
provider on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: match the experimental @example to the migrate stub

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): say a continued run stays in an import's JSON

A dry run, a refusal, and a consent-required run report the run they
would continue, not `null`, and an empty file settles that run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): say which imports --require-password still writes a run for

A dry run or a run without consent writes no run, even when
`--require-password` leaves out every user. Only an import that goes
ahead writes one, with those users recorded as skipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): drop the README pointer from the release changeset

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changeset): stop calling clerk migrate experimental in the final-testing changeset

#604 landed with the sentence this branch drops from the other migrate
changesets. Also adds the Oxford comma to a comment #604 added.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): steer --service-account to the key file's path

A key passed to --service-account as JSON shows up in `ps`, even when the
shell expands it from a variable, and lands in shell history when typed.
The README, the flag table, and --help now point to the file's path, and a
warning covers the JSON case and CI. The no-prompt error names only the
path, and the README no longer claims a CI secret stays off disk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

v4.2.1-canary.981e9c8

Toggle v4.2.1-canary.981e9c8's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
feat(logs): add event filter flags to `clerk logs list` (#615)

* feat(logs): add event filter flags to `clerk logs list`

Add --type, --user, --identifier, --actor, --subject, --session, --client,
--ip, --trace, --impersonator, --payload-filter, --fields, --match and
--end-user-only, mapped to the GET /v1/logs query parameters and sent on
every auto-paged request. Combinations the Backend API rejects fail as
usage errors before a key is resolved. --fields adds a PAYLOAD column to
the table.

Refs CORE-4343

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(logs): escape payload control characters and scope the E2E poll to the test user

The PAYLOAD column prints end-user strings, so escape control characters
(C1 included) before they reach the terminal. The E2E setup waited for the
new user's log among the 100 newest of a test application shared with
concurrent CI runs, which pushed it out; poll with --user instead, and drop
the --type test's dependence on that one log.

Refs CORE-4343

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(logs): reject empty filter values and leave payload limits to the API

An empty string filter (`--user "$UNSET"`) was dropped, and the API treats
an empty value like no filter, so the run listed every log. Every string
filter flag now fails as a usage error on an empty value.

The CLI no longer copies the API's payload path limits (count, depth,
value length, duplicates): they would go stale when the API changes, the
API's 422 is more useful, and the value length counted UTF-16 units while
the API counts bytes. Syntax checks stay.

Also clarify that --match any includes --payload-filter and that --session
matches the session that made the request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

v4.2.1-canary.88595c4

Toggle v4.2.1-canary.88595c4's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
fix(migrate): count users a continue only attached to apart from impo…

…rts (#609)

* fix(migrate): count users a continue only attached to apart from imports

A continue that finished attaching identifiers to a user an earlier
attempt created counted that user as imported again: "2 users already
imported are left alone", then "Imported: 2" for one new user. Once
nothing is left pending, those users now count under "Finished
attaching" (`result.attached` in --json), and the continue's opening
line says they get the identifiers left to attach rather than calling
them left alone. An attach that fails again counts as neither, and the
summary's "Identifiers left to attach" names it.

Fixes AIE-2013

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(migrate): don't count a refused re-attach as finished

A continue whose re-attach Clerk refused left nothing pending, so the
user still counted under "Finished attaching". Only a user whose
identifiers all attached counts there now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(migrate): pin that an earlier refusal doesn't block "Finished attaching"

A continue that attaches what was left counts the user as finished,
whatever the earlier attempt's notes say: they hold its 429 retries,
a phone dropped on the create, and refusals it already reported. The
test pins it, and the docs now say "every identifier left to attach".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(migrate): list "Finished attaching" next to "Imported"

Keeps the two green counts together, and clears the formatSummary
conflict with #606, which adds "Not confirmed" after "Failed".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(migrate): pin that a partial attach isn't counted as finished

Every attach-only test had one pending identifier. This one has two: the
email attaches and the phone gets no answer, so the user is counted
neither as attached nor as ok on the progress bar.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(migrate): say "finished" on the bar when a continue has attaches left

An attach-only user counts in the bar's ok tally, so "created" contradicted
"Imported: 0" in the summary right under it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): say every pending identifier in the attached changeset

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migrate): qualify progress output by mode; scope "once attached" in changeset

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>