TalkJS CLI
Create a TalkJS project or configure an existing one from your terminal.
If you want your coding agent to add chat to your app, start with Agent Skills. To configure an existing TalkJS project by asking your agent, connect it to TalkJS with MCP.
With Node.js 22.18 or later, run:
npm install --global @talkjs/cliYou can also run any command below with npx @talkjs/cli in place of talkjs.
Trying TalkJS for the first time? Create a project without signing up:
talkjs anonymous-account createThe CLI selects the new test app and prints its app ID. Use that ID when you add a TalkJS SDK to your app. Each time you run create, you get a new project.
Already have a TalkJS project? Run talkjs login. When you run it interactively, the CLI opens your browser so you can choose the project and approve access to its test app.
Changing directories keeps the same app selected. Run talkjs whoami to check which app a command will affect, talkjs login to select another project, or talkjs logout to disconnect.
Run talkjs settings get to see the four settings below for the selected app. For example, set the app name and the default language of its chat UI, then read the language back:
talkjs settings set name "My chat app"
talkjs settings set defaultLocale fr-FR
talkjs settings get defaultLocale| Setting | How to use it |
|---|---|
name | Set the display name of the selected test app. |
defaultLocale | Set the default language of the chat UI. |
authentication | Choose optional or required. Set up user authentication in your backend before switching to required. |
custom | Store app-specific values that chat clients may read. Use custom.<key> to read, write, or remove a single field. |
For example, to store a website URL and then read it back:
talkjs settings set custom.websiteUrl "https://example.com"
talkjs settings get custom.websiteUrlUse talkjs settings unset custom.websiteUrl to remove that field. For a bulk update, pass a JSON object with string values, for example talkjs settings set custom '{"websiteUrl":"https://example.com"}'. Its entries merge with existing fields. A null entry removes that field. Passing null for the entire object clears all custom fields.
Run this when you’re ready to add the selected project to your TalkJS account:
talkjs anonymous-account claimSign in or create an account in your browser, then choose Claim and connect CLI. Your app ID stays the same, and the CLI connects to the claimed project. To claim a different anonymous project saved on this computer, pass its app ID to the command.
Your backend uses secret keys to sign user tokens and call the REST API. Run talkjs secret-keys list to see key IDs and which key signs webhooks. Use an ID from that list in the commands below. Both get and create print the secret value. Store it in your backend and keep it out of browser code, shared logs, and agent transcripts. About secret keys
| Command | What it does |
|---|---|
talkjs secret-keys get <id> | Show the secret for an existing key. |
talkjs secret-keys create | Generate a new key. |
talkjs secret-keys set <id> usedForWebhooks true | Choose an active key to sign webhooks. |
talkjs secret-keys set <id> active false | Deactivate a key. If it signs webhooks, switch to a replacement first. Use true to reactivate it. |
talkjs secret-keys delete <id> | Delete an inactive key. |
Pass --json for machine-readable output. For example, after setting the locale above, talkjs settings get defaultLocale --json prints:
{"status":"ok","value":"fr-FR"}Results go to stdout. Warnings and errors go to stderr, and a failed command exits with status 1. The JSON output of anonymous-account create contains an access token and a private claim URL.
For login and anonymous-account claim, --no-open prints the link so you can open it yourself on the computer running the CLI. The command waits for browser approval. With --json, the link goes to stderr.