Reference

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

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

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

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.

Reference

Error codes

Tool failure shape

Config

Skills