paperclipai/paperclip · error · Error

Invalid --persona value. Use board or agent.

Error message

Invalid --persona value. Use board or agent.

What it means

parsePersona validates the --persona flag and rejects any value that is not exactly "board" or "agent". The persona determines whether the profile behaves as a board operator or an agent.

Source

Thrown at cli/src/commands/client/context.ts:157

    patch[key] = value;
  }
}

function buildContextPatch(opts: ContextSetOptions): Partial<ClientContextProfile> {
  const patch: Partial<ClientContextProfile> = {};
  setIfProvided(patch, "apiBase", opts.apiBase);
  setIfProvided(patch, "companyId", opts.companyId);
  setIfProvided(patch, "persona", parsePersona(opts.persona));
  setIfProvided(patch, "agentId", opts.agentId);
  setIfProvided(patch, "agentName", opts.agentName);
  setIfProvided(patch, "apiKeyEnvVarName", opts.apiKeyEnvVarName);
  return patch;
}

function parsePersona(value: string | undefined): "board" | "agent" | undefined {
  if (value === undefined) return undefined;
  if (value === "board" || value === "agent") return value;
  throw new Error("Invalid --persona value. Use board or agent.");
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass --persona board or --persona agent.
2. Omit --persona to leave it unchanged.

Example fix

// before
paperclipai context set --persona operator
// after
paperclipai context set --persona board

const PERSONAS = new Set(['board', 'agent']);
function parsePersona(value: string | undefined) {
  if (value === undefined) return undefined;
  if (!PERSONAS.has(value)) throw new Error('Invalid --persona value. Use board or agent.');
  return value as 'board' | 'agent';
}

const isPersona = (v: string): v is 'board' | 'agent' => v === 'board' || v === 'agent';

When it happens

Trigger: Running `paperclipai context set --persona admin` (or any value other than board/agent).

Common situations: Typo; using singular forms like "user"; following outdated docs that list other personas.

Related errors

• Failed to parse JSON at ${filePath}: ${err instanceof Error
• Company ID is required. Pass --company-id, set PAPERCLIP_COM
• Profile name is required
• Unsupported export format: ${value}
• Invalid integer value: ${value}

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/33acfa43b727ab0a. Report an issue: GitHub.