Getting started
Receive your first verification code with Phonekit
Phonekit lets your team and software read texts on company-controlled numbers. This quickstart connects your terminal to an existing workspace, names a number for your project, and receives a fresh verification code without opening the inbox.
Before you start
You need Node.js 20.3 or later, access to a Phonekit workspace, and a number that is active and available to your workflow. Use a test account in an application you are authorized to test. The CLI reads messages; number claiming and workspace administration happen in Phonekit.
Programmatic access is included on every plan. A browser-approved connection reads only the numbers selected during approval and cannot manage lines. Number acquisition, configuration and release need a separately created management credential with its own selected numbers. Phonekit does not send verification SMS or expose general workspace administration through this connection.
Connect your terminal
Start sign-in and approve the request in your browser. Check that the short code on the approval page matches the code in your terminal, then select the numbers this connection can read. On a machine without a browser, open the printed approval link on your own device.
A successful connection stores its key in the system keychain. Where a keychain is unavailable, the CLI reports that it is using an owner-only credentials file. Keep the key out of source control and build logs.
npx phonekit@latest login
npx phonekit@latest number listGive the project a stable number name
Replace the example organization and phone number below with values from your workspace. The link command writes .phonekit.json with the organization and number aliases. It contains no credentials and can be committed so teammates and agents use the same names.
When multiple numbers are readable, choose the one intended for this workflow. A number alias describes a shared resource; it does not reserve that resource against other tests.
npx phonekit@latest link --org your-org --name invitee=+14155550142Mark, send, then wait
Mark the number before asking your application to send its SMS. The mark records the inbox position so the subsequent wait reads a new message rather than an old verification code. Enter the real phone number in the application, trigger its message, then run the wait command.
The code is returned on stdout; context and progress go to stderr. Use the code immediately in the application. Do not paste it into a ticket or log. For automated JS/TS tests, use the SDK directly in the runner. The Playwright guide includes setup and the final signed-in assertion.
npx phonekit@latest message mark --number invitee
# Trigger the SMS in your application now.
npx phonekit@latest code wait --number invitee --timeout 120Questions you may have
What if the SMS arrived before I marked?
A position captured after arrival excludes that message. Use code latest --json and inspect message.receivedAt and message.ageSeconds when deliberately reading an existing receipt. For another attempt, mark before requesting its SMS.
Why can I see a number in the workspace but not in the CLI?
The connection reads the numbers explicitly selected during its approval. Workspace membership and a software credential are separate access routes. Review the connection’s scope and use number list to confirm what this runtime can read.
How do I connect an unattended test runner?
Supply a selected-number read key through the runner’s secret environment. Use the SDK directly in a JS/TS test, or the documented CLI environment configuration for command-based work. The CI workflow shows a complete runner setup.
What if the wait times out?
Check the destination, application send result and whether another task shared the number. The CLI’s exit code 5 means no receipt before its deadline. Confirm those stages before requesting another code; the service may enforce a resend interval.
Can a project alias reserve its number?
An alias names a shared destination; it does not lock the inbox. Use separate numbers for simultaneous verification flows or serialize tasks sharing a destination. The reliability guide explains the distinction.