CLI Reference

The UserDispatch CLI sets up everything in one command — authentication, app creation, widget injection, and MCP configuration.

Installation

No global install required. Run directly with npx:

npx userdispatch init

Requires Node.js 18+.

What it does

The CLI walks through six steps:

Authenticate

Opens your browser to sign in with Google OAuth. A ud_ token is generated (90-day expiry) and you paste it into the terminal. In non-TTY environments (e.g. Claude Code, Codex), a device authorization flow polls automatically — no browser paste needed.

Create organization & app

One POST to /api/cli/setup sends your org name and app name, returns an API key. Existing apps can be reused — the CLI checks before creating.

Install widget

Reads package.json to detect your framework, installs @userdispatch/sdk via your package manager, and adds one <Script> tag before </body> in your layout file.

Configure MCP

Detects agents by config directories, writes MCP config, and stores the token in .env (Claude Code / Cursor) or directly in config. Adds config files to .gitignore.

Verify

Sends one test submission to your own app via your API key to confirm everything works end-to-end.

Summary

Displays a summary of what was created and modified. No additional files written, no network calls.

Manual setup

If you prefer not to use the CLI, you can set everything up by hand in a few minutes.

Create your account and app

Sign up at userdispatch.com with Google. Create an organization, then create an app. Copy the API key from the app settings page — you'll need it for the next two steps.

Add the widget to your site

Paste this script tag before </body> in your HTML layout:

HTML

<script
  src="https://userdispatch.com/widget.js"
  data-api-key="pk_YOUR_API_KEY"
  defer
></script>

For Next.js App Router, use a <Script> component instead. For Nuxt or Astro, add it to your global layout file.

Configure your MCP server

Add this to your .mcp.json (Claude Code) or equivalent agent config:

.mcp.json

{
  "mcpServers": {
    "userdispatch": {
      "type": "url",
      "url": "https://userdispatch.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${USERDISPATCH_TOKEN}"
      }
    }
  }
}

Store your token

Add your API token to .env (and make sure it's in .gitignore):

.env

USERDISPATCH_TOKEN=ud_your_token_here

Test it

Open your app in a browser and submit a piece of feedback via the widget. Check the UserDispatch dashboard — the submission should appear within seconds. Then ask your coding agent to list recent submissions using the MCP server to confirm the full loop works.

Security & privacy

✓Token stored locally — your ud_ token is written to .env and auto-added to .gitignore. It is never committed.
✓Minimal file changes — the CLI modifies one layout file (script tag), one or two MCP config files, and .gitignore. Nothing else.
✓Fully auditable — the CLI source code is in the cli/ directory of the published npm package. Read every line before you run it.

Flags

Flag	Description
--token <token>	Skip browser auth and use this ud_ token directly. Auto-promotes to CI mode in non-TTY environments.
--org <name>	Organization name (skips prompt). Used when creating a new org.
--app <name>	App name (skips prompt). Slug is auto-generated from the name.
--framework <type>	Override framework detection. Values: next-app, next-pages, vite, cra, nuxt, sveltekit, astro, static.
--agent <id>	Override agent detection. Values: claude-code, cursor, windsurf, claude-desktop, vscode.
--ci	Non-interactive mode. Skips all prompts and uses defaults or flag values.

Non-interactive mode

For CI pipelines or AI coding agents that can't use interactive prompts, use --ci or pass --token (auto-promotes to CI mode in non-TTY environments):

CI / Coding agent

npx userdispatch init \
  --token ud_your-token \
  --app my-app \
  --ci

In CI mode, all prompts are skipped. The CLI uses flag values or sensible defaults (current directory name for app name, etc.). All detected agents are configured automatically.

Framework detection

The CLI auto-detects your framework from package.json dependencies and project structure:

Framework	Detection	Widget injection
Next.js (App Router)	next in dependencies + app/layout.tsx	Script component before </body>
Next.js (Pages Router)	next in dependencies + pages/_document.tsx	Script tag in _document.tsx
Vite	vite in dependencies	Script tag in index.html
Create React App	react-scripts in dependencies	Script tag in public/index.html
Nuxt	nuxt in dependencies	Manual (nuxt.config.ts shown)
SvelteKit	@sveltejs/kit in dependencies	Script tag in src/app.html
Astro	astro in dependencies	Manual (instructions shown)
Static HTML	index.html in project root	Script tag in index.html

Agent detection

The CLI detects installed AI coding agents and configures MCP for each:

Agent	Config path	Detection
Claude Code	.mcp.json (project root)	Always offered
Cursor	.cursor/mcp.json	.cursor/ directory exists
Windsurf	~/.codeium/windsurf/mcp_config.json	~/.codeium/windsurf/ exists
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	~/Library/Application Support/Claude/ exists
VS Code Copilot	.vscode/mcp.json	.vscode/ directory exists

Troubleshooting

ERR_TTY_INIT_FAILED

The CLI requires an interactive terminal for prompts. If running from a coding agent, use --token and --ci flags for non-interactive mode.

Auth token not working

Make sure you copied the full ud_ token including the prefix. Tokens expire if unused for an extended period — generate a new one at userdispatch.com/cli/auth.

Widget not injected

The CLI looks for specific layout files based on your framework. If it can't find one, it shows manual instructions. You can override detection with --framework.

MCP config not written

Agents are detected by the presence of their config directories. Use --agent to force configuration for a specific agent.