diff --git a/agent-skills.mdx b/agent-skills.mdx index 7d73d9870..0012ae7ad 100644 --- a/agent-skills.mdx +++ b/agent-skills.mdx @@ -45,9 +45,12 @@ Run the installer in your project root: npx @cometchat/skills add ``` -It detects your React or Angular setup and opens a picker to install the skills for -the AI agent(s) you use. To pin a single agent — useful in CI or a Dockerfile — pass -`--ide`: +It detects your React or Angular setup and installs the skills for **Claude Code** +by default. It also connects the CometChat Docs MCP server (`cometchat-docs`) for +that agent; pass `--no-mcp` to skip it. In Claude Code, approve `cometchat-docs` +when `claude` asks on first start in the project — until then `claude mcp list` +shows it as *Pending approval*, and the skills fall back to the docs site. To +install for a different agent, pass `--ide`: ```bash npx @cometchat/skills add --ide claude # Claude Code → .claude/skills/ @@ -76,8 +79,8 @@ npx @cometchat/skills add --ide all # every supported agent Claude Code, Kiro, and Replit get a native `SKILL.md` tree. The other agents get an orienting router plus a `./.cometchat/skills` tree. Add `--global` (Claude -Code, Kiro, and Replit only) to install into your user-level directory instead of -the project. +Code only) to install into your user-level `~/.claude/skills` instead of the +project. ## Use it @@ -116,7 +119,7 @@ fetching them from your dashboard: - **Fetch from your dashboard (recommended)** — the skill runs the standalone CometChat CLI for you, on demand: it opens the dashboard login in your browser, lets you pick one of your **existing** apps, pulls the credentials, - and writes a neutral `.cometchat/config.json`. You can also run the CLI yourself + and writes a neutral `.cometchat/config.json`. You can also [run the CLI yourself](/cli) — it works on its own, in a script, or in CI. - **Paste manually** — copy App ID, Region, and Auth Key from **Dashboard → Your App → Credentials** if you'd rather not log in. @@ -222,8 +225,11 @@ existing files — you don't have to know the component or prop names. ## Manage the skills - **Update** — re-run `npx @cometchat/skills add` to pull the latest skills; it overwrites the installed skill tree in place. -- **Inspect** — `npx @cometchat/skills list` shows the installed skills, and `npx @cometchat/skills doctor` runs an environment health check. -- **Uninstall** — delete the installed skill directory for your agent (for example `.claude/skills/cometchat*`, `.agents/skills/`, or `./.cometchat/skills`). +- **Inspect** — `npx @cometchat/skills list` lists the skills the pack ships, and `npx @cometchat/skills doctor` runs an environment health check. +- **Uninstall** — there's no uninstall command. Remove what `add` wrote for your agent: + - **The skill files** — `.claude/skills/cometchat*` (Claude Code), `.kiro/skills/cometchat*` (Kiro), `.agents/skills/cometchat*` (Replit), or `./.cometchat/skills` (every other agent). + - **The router block** — for the other agents, `add` also writes a block between `` and `` into the agent's instruction file: `AGENTS.md` (Cursor, Codex, Antigravity, Continue), `.windsurfrules`, `.github/copilot-instructions.md`, `.clinerules/cometchat.md`, `GEMINI.md`, or `CONVENTIONS.md` (Aider). Delete that block and keep the rest of the file. + - **The Docs MCP entry** — remove the `cometchat-docs` server from `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.gemini/settings.json` (Gemini), or `.codex/config.toml` (Codex). Other agents get no MCP entry. - **Version control** — commit the skill files so your whole team shares the same setup. Do **not** commit `.cometchat/config.json` or the generated env file — they hold your Auth Key. ## Troubleshooting diff --git a/cli.mdx b/cli.mdx new file mode 100644 index 000000000..a12be6a4c --- /dev/null +++ b/cli.mdx @@ -0,0 +1,264 @@ +--- +title: "CometChat CLI" +sidebarTitle: "CLI" +description: "Authenticate against the CometChat dashboard, provision app credentials, toggle features, and manage the AI agent skills — all from your terminal, with JSON output for scripting and CI." +canonical: "https://www.cometchat.com/docs/cli" +--- + +CometChat ships two complementary command-line tools: + +| Tool | Package | What it does | +| --- | --- | --- | +| **Credentials CLI** (`cometchat`) | `@cometchat/skills-cli` | Dashboard authentication + app-credential provisioning + feature toggles | +| **Skills installer** | `@cometchat/skills` | Install, list, and verify the [AI Agent Skills](/agent-skills) | + + +Despite its package name, `@cometchat/skills-cli` is the **credentials** tool — +it doesn't install skills. It provides a `cometchat` command, so the CLI's own +messages (for example *"Run `cometchat auth login`"*) use that short form. This +page runs it through `npx`; `cometchat auth login` and +`npx @cometchat/skills-cli auth login` are the same command. The skills +themselves are installed by `@cometchat/skills`. + + + +The credentials CLI is **standalone** — use it on its own, in a script, or in CI. +It's a pure dashboard/API client: it authenticates, fetches your app credentials +(App ID / Region / Auth Key), and writes a neutral `.cometchat/config.json`. By +design it does **not** detect your framework, write env files, or generate code, +so it stays framework-agnostic and works with any stack. The +[agent skills](/agent-skills) are one consumer that can run it for you — but the +CLI doesn't require them. + + +Both run through `npx` with no global install, and most commands accept `--json` +for machine-readable output (the exceptions are `config set` and `config path`, +which print plain text). + +## Prerequisites + +- **Node.js 18+** — both CLIs run through `npx`. +- A **CometChat account** — [sign up free](https://app.cometchat.com). `auth login` opens the dashboard in your browser to authenticate. + +--- + +## Credentials CLI — `@cometchat/skills-cli` + +Its only job is authenticating against the CometChat dashboard and fetching your +**App ID / Region / Auth Key**, then writing a neutral `.cometchat/config.json` +that any tool — your own scripts, a CI job, or the agent skills — can read. + +### Quick start + +```bash +# 1. Authenticate against the dashboard (opens your browser) +npx @cometchat/skills-cli auth login + +# 2. List the apps on your account +npx @cometchat/skills-cli provision list --json + +# 3. Select an app, fetch its creds, write .cometchat/config.json +npx @cometchat/skills-cli provision run + +# 4. Inspect the local config you just wrote +npx @cometchat/skills-cli config show --json +``` + +### Authenticate + +```bash +npx @cometchat/skills-cli auth login +``` + +Opens your browser at the CometChat dashboard for device authentication and +stores the bearer token in your OS keychain (falling back to a `chmod 600` file). + +| Command | Purpose | +| --- | --- | +| `auth login` | Sign in via the dashboard (device auth) | +| `auth status` | Show whether you're signed in | +| `auth me` | Print the authenticated account | +| `auth logout` | Clear the stored token | +| `auth signup` | Create a CometChat account | + +### Provision credentials + +```bash +npx @cometchat/skills-cli provision run +``` + +Fetches the app's **App ID / Region / Auth Key** and writes a neutral +`.cometchat/config.json`, then prints the selected app (`✓ App ()`) +and the config path. Add `--json` to get the credentials as JSON instead. It +writes **no** framework env file — read `config.json` and set your framework's +env vars (`.env` / `VITE_` / `NEXT_PUBLIC_` …) yourself, or let the agent skills +do it. + +Which app it uses depends on how many your account has: + +- **One app** — it uses that app. +- **Several apps** — it lists them and asks you to pick one, or to enter `n` to + create a new app. This needs an interactive terminal; in a script, use + `provision list` and then `provision use --app-id `. +- **No apps** — it exits with an error. Create one first with + `provision create --name `. + +| Command | Purpose | +| --- | --- | +| `provision run` | Select an app (see above), fetch its creds, write config | +| `provision list` | List the apps on your account | +| `provision create --name ` | Create a new app (`--name` required) | +| `provision use --app-id ` | Select a specific app by id | + +Create a new app non-interactively — `--name` is required, `--region` and +`--industry` are optional: + +```bash +npx @cometchat/skills-cli provision create --name "My Chat" --region us +``` + +The config file `provision` writes: + +```json +{ + "$schema": "https://cometchat.com/schemas/config.json", + "version": 1, + "appId": "…", + "region": "us", + "authKey": "…", + "appName": "My Chat", + "plan": "…", + "industry": "…" +} +``` + + +`.cometchat/config.json` contains your **Auth Key**. The CLI writes it readable +by your user only (`chmod 600`) and adds it to `.gitignore` for you. If the file +is **already tracked** by git, the CLI warns you — a `.gitignore` entry doesn't +untrack it, so run `git rm --cached .cometchat/config.json` and commit. The Auth +Key is for **development only**; in production, mint a per-user **auth token** on +your backend and log in with `loginWithAuthToken()` instead of shipping the Auth +Key to a client. + + +### Manage config + +Read and edit the local `.cometchat/config.json` (credential/app state only): + +| Command | Purpose | +| --- | --- | +| `config init [--app-id ] [--region ] [--auth-key ]` | Create or update the config from the given values — no dashboard login needed | +| `config get ` | Read a single value | +| `config set ` | Write a single value | +| `config show` | Print the full config | +| `config path` | Print the config file location | + + +`config show` prints the **Auth Key** in clear text, with or without `--json`, +and so do `config get authKey` and `provision run --json`. Avoid running them +while screen-sharing or anywhere the output is logged. + + +### Toggle features + +Enable or disable app features from the terminal. These commands call the +dashboard, so run `auth login` first: + +| Command | Purpose | +| --- | --- | +| `features list` | List available features and their state | +| `features enable ` | Turn a feature on | +| `features disable ` | Turn a feature off | +| `features ai-key ` | Set the app's OpenAI key that AI features need | + +Every `features` command targets the app in `.cometchat/config.json`. Pass +`--app-id ` to target a different app: + +```bash +npx @cometchat/skills-cli features list --app-id "$COMETCHAT_APP_ID" --json +``` + +AI features need an OpenAI key before they can run. The key is a required +argument — pass it from an environment variable so it doesn't land in your shell +history: + +```bash +npx @cometchat/skills-cli features ai-key "$OPENAI_API_KEY" +``` + +--- + +## Skills CLI — `@cometchat/skills` + +Installs and manages the [AI Agent Skills](/agent-skills) that let your coding +agent build with CometChat. + +```bash +npx @cometchat/skills add +``` + +| Command | Purpose | +| --- | --- | +| `detect` | Probe the current project (framework, UI Kit, version conflicts) | +| `add [--ide ] [--no-mcp]` | Install the skills for an AI agent (default: Claude Code) and connect the CometChat Docs MCP (`--no-mcp` skips it) | +| `list` | List the skills this pack ships | +| `info ` | Show a skill's triggers + compatibility | +| `verify [tier]` | Run the skill quality gates | +| `catalog` | Refresh the component catalog from the installed UI Kit | +| `doctor` | Environment health check | + +`add` doesn't prompt: with no `--ide` it installs for Claude Code. See +[Agent Skills](/agent-skills) for the supported agents and their `--ide` values, +`--global`, and the prompt-driven workflow. + +--- + +## Scripting and CI + +`auth login` is interactive: it opens a browser and waits for you to approve the +sign-in, so on a CI runner it times out (`TIMEOUT`). In CI, skip the dashboard +login and write the config straight from your pipeline secrets with +`config init`, which needs no login: + +```bash +# Write .cometchat/config.json from CI secrets, then install the skills for Claude Code +npx @cometchat/skills-cli config init --app-id "$COMETCHAT_APP_ID" --region "$COMETCHAT_REGION" --auth-key "$COMETCHAT_AUTH_KEY" +npx @cometchat/skills add --ide claude +``` + + +Don't add `--json` to `config init` in CI — its JSON output includes the Auth +Key, which would end up in your build logs. Store the App ID, Region, and Auth +Key as masked CI secrets. + + +The commands that call the dashboard — `provision` and `features` — need +`auth login`, so run them from your own machine rather than in CI. Everywhere +else, most commands support `--json` (the exceptions are `config set` and +`config path`, which print plain text). + +Commands **exit non-zero on failure** and surface dashboard errors verbatim (for +example `ACCESS_DENIED`, `EXPIRED`, `TIMEOUT`, `ABORTED`), so a broken auth or +provisioning step fails the CI job loudly instead of continuing with empty +credentials. + +## Next steps + + + + Install the skills and build CometChat from natural-language prompts + + + Connect CometChat to any Model Context Protocol–compatible agent + + + The manual React UI Kit setup, credentials and all + + + The manual Angular UI Kit setup, credentials and all + + + Open the CometChat dashboard + + diff --git a/docs.json b/docs.json index 035cebab9..8882cabdf 100644 --- a/docs.json +++ b/docs.json @@ -98,6 +98,7 @@ "group": "Developer Tools", "pages": [ "agent-skills", + "cli", "mcp-server" ] } diff --git a/index.mdx b/index.mdx index 66a7c14d6..009a8659d 100644 --- a/index.mdx +++ b/index.mdx @@ -124,7 +124,7 @@ canonical: "https://cometchat.com/docs" Additional solutions to customize your CometChat experience.

- + - Let your AI coding agent add CometChat chat & calling to your React app. + Let your AI coding agent add CometChat chat & calling to your React or Angular app. + + + + Authenticate, provision credentials, and manage the skills from your terminal. +