---
title: Reference
description: Stable, machine-readable error codes for CLI and MCP.
---

CLI and MCP failures use stable, machine-readable codes. An `AMBIGUOUS` response includes candidate ids in `details.matches` so agents can retry with an exact id.

## Error codes

```bash lineNumbers
UNAUTHENTICATED       # run neram login
MISSING_CONFIG        # config fetch failed; check network or env overrides
AMBIGUOUS             # name matched multiple records; retry with an id from details.matches
NOT_FOUND             # project or task does not exist
FORBIDDEN             # caller lacks access
ORGANIZATION_REQUIRED # choose a workspace and sign in again
CONFIRMATION_REQUIRED # exact Organization id/slug or confirmation is missing
VALIDATION            # bad input shape or value
```

```json lineNumbers
{
  "error": {
    "code": "AMBIGUOUS",
    "message": "Multiple projects matched \"Website\".",
    "details": {
      "matches": [
        { "id": "j57abc...", "name": "Website" },
        { "id": "j57def...", "name": "Website" }
      ]
    }
  }
}
```

## Tool failure shape

MCP tool failures return `isError: true` with `content: [{ type: "text", text: JSON.stringify({ error }) }]`. They are not protocol exceptions. The same shape is returned by `neram --json` commands on failure.

## Config

Public CLI config is at `/.well-known/neram-agent.json`. It exposes `convexUrl`, `clerkFrontendApiUrl`, and `oauthClientId`. Override only for local dev with `NERAM_CONVEX_URL`, `NERAM_CLERK_FRONTEND_API_URL`, `NERAM_CLERK_OAUTH_CLIENT_ID`.

## Skills

The `neram` skill (`skills/neram/SKILL.md`, grouped as "Neram" in `skills.sh.json`) teaches an agent to use the CLI and MCP surfaces above instead of browser automation.