Install the Beatra Skill and sign in with a device code
Install the Beatra Skill in Claude Code, Cursor, Codex, or WorkBuddy with one message, approve a device-code sign-in once, and keep the Skill up to date.
The Beatra Skill gives your agent every Beatra capability (images, video, music, speech, and public social data) in one package. You install it by sending your agent one message. The Skill then signs in to Beatra with a device code that you approve once in the browser, and keeps that sign-in on your computer. Installing and signing in are free; generating media uses Beatra credits.
Before you start
| What | Needed |
|---|---|
| Agent | Claude Code, Cursor, Codex, WorkBuddy, or another agent that can install a Skill and run scripts |
| Python | 3.10 or newer on the machine where the agent runs. The Skill's scripts use only the standard library. |
| Network | HTTPS. The Skill picks the international or the mainland China Beatra hosts for this computer by itself. |
| Account | A Beatra account. The approval page lets you sign in or create one. |
| Cost | Free to install and sign in. Generation uses credits: Billing & usage. |
Send the install message
The agent downloads the Skill package from Beatra, checks its SHA-256 checksum before extracting it, and installs the beatra folder with its own Skill mechanism, next to your other Skills.
Checkpoint
- The agent says the Beatra Skill is installed.
Approve the device code in the browser
The Skill runs its sign-in helper, scripts/authorize.py. The helper requests a device code from Beatra and opens the approval page in your browser; when it cannot open a browser, the agent shows you the link. On the page, sign in, then choose Allow. The page stays open for up to an hour, and the agent picks up your approval by itself.
Checkpoint
- The approval page shows "Approved", then "Connected" once your agent picks up the sign-in.
- The agent reports that Beatra is ready. The helper checks the new connection with a free request, so nothing is charged.
Make a first request
Some agents load Skills only when a session starts. If yours does, open a new session first, then describe what you want:
Checkpoint
- The agent confirms a Beatra task was created, then returns the result and the credits it used.
Find the computer in the console
Open Devices in the console. Every computer where the Skill signed in is listed there, and you can disconnect any of them at any time.
Checkpoint
- Devices lists this computer as connected.
What stays on your computer
The sign-in is saved only in your user folder, under ~/.beatra/: credentials.json holds the device credential, and installation.json holds a stable installation reference that is not secret. On macOS and Linux only your user can read the folder (mode 0700, files 0600). Every Beatra Skill on the computer shares this one sign-in, so installing a second Beatra Skill needs no second approval.
Stay signed in
- The sign-in renews each time the Skill is used and ends after 15 days without use.
- To reconnect after that, or after the computer was disconnected in the console, ask the agent to run
python3 scripts/authorize.pyagain and approve once. - To use another Beatra account, ask the agent to run
python3 scripts/authorize.py --forceand approve with that account.
Update the Skill
The Skill stays at the version you installed. At most once a day it checks the store or tool you installed it from, and when a newer version is there it prints one line with the command that updates it. A copy installed with the install message updates when you send the install message again. Every other source is listed in Troubleshooting: version mismatch.
Remove the Skill
Ask the agent to uninstall Beatra. It runs the Skill's scripts/uninstall.py first. When this is the last Beatra Skill on the computer, the script disconnects the computer from Beatra and deletes the sign-in files in ~/.beatra/; when another Beatra Skill remains, the shared sign-in stays. The agent then deletes the Skill folder.
If a step does not work
Send the same install message again. The agent keeps the steps that are already correct and continues from the part that still needs attention. For a specific message:
BEATRA_AUTH_PENDING,access_denied,expired_token, orBEATRA_AUTH_REQUIRED: Troubleshooting: sign-in fails.- The WeChat QR code or a verification code: Sign-in troubleshooting.
- Insufficient credits: Troubleshooting: not enough credits.
To compare the Skill with Beatra MCP and the REST API, see Choose how to use Beatra. Every tool the Skill can call is in the MCP tool reference.
Last updated