For AI agents: Find a documentation index at https://talkjs.com/llms.txt (full content at https://talkjs.com/llms-full.txt). Get a markdown version of any page by appending .md to its URL path.

TalkJS CLI

Create a TalkJS project or configure an existing one from your terminal.

View as Markdown

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.

Install the CLI

With Node.js 22.18 or later, run:

npm install --global @talkjs/cli

You can also run any command below with npx @talkjs/cli in place of talkjs.

Create or connect a project

Trying TalkJS for the first time? Create a project without signing up:

talkjs anonymous-account create

The 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.

Read and change settings

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
SettingHow to use it
nameSet the display name of the selected test app.
defaultLocaleSet the default language of the chat UI.
authenticationChoose optional or required. Set up user authentication in your backend before switching to required.
customStore 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.websiteUrl

Use 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.

Keep a project you created without signing up

Run this when you’re ready to add the selected project to your TalkJS account:

talkjs anonymous-account claim

Sign 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.

Manage secret keys

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

CommandWhat it does
talkjs secret-keys get <id>Show the secret for an existing key.
talkjs secret-keys createGenerate a new key.
talkjs secret-keys set <id> usedForWebhooks trueChoose an active key to sign webhooks.
talkjs secret-keys set <id> active falseDeactivate 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.

Use the CLI in scripts

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.