Skip to main content

​
command not found: userintuition-mcp

The binary isn’t on your PATH. Pick the install style you used and verify:
If which is empty, your global npm bin directory isn’t on PATH. Run npm config get prefix and add <prefix>/bin to PATH.

​
No authentication found

The CLI could not find a saved OAuth login, a saved API key, or USERINTUITION_API_KEY. Start with:
For non-interactive CI, set USERINTUITION_API_KEY as a secret. Common causes:
  1. Not exported in the current shell.
  2. Set in ~/.zshrc but the shell didn’t reload. Open a new terminal or source ~/.zshrc.
  3. Running under sudo or a different user. sudo strips most env vars — prefix the call: sudo USERINTUITION_API_KEY=ui_sk_... userintuition-mcp call …
  4. CI secret not wired. Confirm the variable is set as a secret in your CI provider and exposed to the step that runs the CLI.

​
401 Unauthorized from the backend

The key is read but the backend rejected it.
  • Revoked or rotated. Run userintuition-mcp login, then userintuition-mcp api-key create --name "Replacement", and update any CI secret.
  • Wrong environment. Production keys (ui_sk_live_...) don’t work against staging and vice versa. Check BACKEND_URL if you’ve overridden it.
  • Typo / wrapping whitespace. echo "$USERINTUITION_API_KEY" | wc -c — should match expected key length (no trailing newline issues).

​
Invalid input for <tool>: …

Zod schema validation failed before the CLI tried to call the backend. The error message names the offending field.
Re-read the schema:
Common variants:
  • Missing required flag. Add it.
  • String where a number/boolean/array is expected. Make sure the value is JSON-parseable: --target 25 not --target "twenty-five"; --include '["transcript"]' not --include transcript.
  • Nested objects. Use --input-json rather than flags.

​
Tool call hangs or times out

Network egress to api.userintuition.ai may be blocked or slow.
If the curl works but the CLI hangs, the tool may legitimately be long-running (e.g. generate_report, which takes 30–120 seconds). Check the equivalent operation in the dashboard — if it normally takes minutes, the CLI behaves the same way. If you’re on a corporate network, confirm a proxy hasn’t TLS-intercepted the connection. Node respects HTTPS_PROXY; set it explicitly if needed.

​
EACCES / permission denied on the binary

After a manual tsc build, dist/index.js may not be executable.
npm publish handles this automatically — only a concern for local builds.

​
Output isn’t valid JSON

The CLI writes the tool’s text response verbatim to stdout. Most tools return JSON; a few (e.g. PowerPoint generation) return a URL or status string. Use userintuition-mcp describe <tool> to confirm the response shape, and check whether the tool returned an {"error": …} envelope on a logical failure. If stderr contents are being mixed into your pipe, redirect them out: userintuition-mcp list_studies 2>/dev/null | jq ..

​
Still stuck?

Run the equivalent MCP call through the official inspector to isolate whether the issue is the CLI or the underlying tool:
If it reproduces there, the bug is in the tool or the backend — open an issue at github.com/userintuition. If it only reproduces in the CLI, please include the exact command, your CLI version (npm ls -g @userintuition-ai/mcp), and Node version (node --version).