---
url: https://talkjs.com/docs/Developer_Tools/CLI/
title: "TalkJS CLI | Developer Tools | TalkJS Docs"
---

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.

If you want your coding agent to add chat to your app, start with [Agent Skills](https://talkjs.com/docs/Developer_Tools/Agent_Skills/). To configure an existing TalkJS project by asking your agent, [connect it to TalkJS with MCP](https://talkjs.com/docs/Developer_Tools/MCP/).

## Install the CLI

With Node.js 22.18 or later, run:

```sh
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:

```sh
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](https://talkjs.com/docs/UI_Components/). 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:

```sh
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](https://talkjs.com/docs/Features/Language_Support/) of the chat UI. |
| `authentication` | Choose `optional` or `required`. Set up [user authentication](https://talkjs.com/docs/Features/Security/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:

```sh
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:

```sh
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](https://talkjs.com/docs/Features/Security/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. |

## Use the CLI in scripts

Pass `--json` for machine-readable output. For example, after setting the locale above, `talkjs settings get defaultLocale --json` prints:

```json
{"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.
