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
INCOMPLETE_SUBTASKS # completing a task with unfinished subtasks; pass confirmIncompleteSubtasks
CASCADE_CONFIRMATION_REQUIRED # deleting a task with children; pass confirmCascade
VALIDATION # bad input shape or value{
"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.
Local MCP inspection
npx neram mcp list --json # tools, resources, resource templates, prompts — no client needed
npx neram mcp serve --port 3030 # loopback-only Streamable HTTP for Inspector testing
npx neram mcp install cursor --write --merge # opt-in write; print-only by defaultmcp serve binds 127.0.0.1 only and caps request bodies. mcp install prints the client snippet without writing files unless --write is passed; it refuses to overwrite malformed or unreadable configs, and re-running without --merge will not clobber an existing neram entry.
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.