paperclipai/paperclip · error · Error

Company ID is required. Pass --company-id, set PAPERCLIP_COM

Error message

Company ID is required. Pass --company-id, set PAPERCLIP_COMPANY_ID, or set context profile companyId via `paperclipai context set`.

What it means

Thrown by resolveCommandContext() in common.ts when opts.requireCompany is true and no companyId can be resolved from --company-id, the PAPERCLIP_COMPANY_ID env var, or the active context profile's companyId. Company scope is a control-plane invariant for company-scoped commands; the CLI refuses to call the API without one rather than implicitly acting on the wrong/default company.

Source

Thrown at cli/src/commands/client/common.ts:68

  opts?: { requireCompany?: boolean },
): ResolvedClientContext {
  const context = readContext(options.context);
  const { name: profileName, profile } = resolveProfile(context, options.profile);

  const apiBase = resolveApiBase(options, profile);

  const resolvedApiKey = resolveApiKey(options, profile);
  const explicitApiKey = resolvedApiKey.value;
  const storedBoardCredential = explicitApiKey ? null : getStoredBoardCredential(apiBase);
  const apiKey = explicitApiKey || storedBoardCredential?.token;

  const companyId =
    options.companyId?.trim() ||
    process.env.PAPERCLIP_COMPANY_ID?.trim() ||
    profile.companyId;

  if (opts?.requireCompany && !companyId) {
    throw new Error(
      "Company ID is required. Pass --company-id, set PAPERCLIP_COMPANY_ID, or set context profile companyId via `paperclipai context set`.",
    );
  }

  // Agent-authenticated mutations (checkout, release, interactions, PATCH of an
  // in-progress issue) require the X-Paperclip-Run-Id header (the server returns
  // "401 Agent run id required" without it). Source it from --run-id, else the
  // PAPERCLIP_RUN_ID env the adapter/embodiment context already exports.
  const runId = options.runId?.trim() || process.env.PAPERCLIP_RUN_ID?.trim() || undefined;

  const api = new PaperclipApiClient({
    apiBase,
    apiKey,
    runId,
    recoverAuth: explicitApiKey || !canAttemptInteractiveBoardAuth()
      ? undefined
      : async ({ error }) => {
          const requestedAccess = error.message.includes("Instance admin required")

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass it inline: `--company-id cmp_xxx`.
2. Or export it: `export PAPERCLIP_COMPANY_ID=cmp_xxx`.
3. Or persist it in the profile: `paperclipai context set --profile default --company-id cmp_xxx` (then it applies to every command using that profile).
4. Confirm --profile selection if you have multiple profiles with different companies.

Example fix

// before
paperclipai agent local-cli agt_1
// after (pick one)
paperclipai agent local-cli agt_1 --company-id cmp_xxx
export PAPERCLIP_COMPANY_ID=cmp_xxx
paperclipai context set --company-id cmp_xxx

function resolveCompanyId(opts: { companyId?: string }, profile: { companyId?: string }): string {
  const id = opts.companyId?.trim() || process.env.PAPERCLIP_COMPANY_ID?.trim() || profile.companyId?.trim();
  if (!id) {
    throw new Error('Company ID required. Set one of: --company-id, $PAPERCLIP_COMPANY_ID, or context profile companyId.');
  }
  return id;
}

function isCompanyId(v: string): v is `${'cmp_'}` is too narrow — instead:
function looksLikeCompanyId(v: unknown): boolean {
  return typeof v === 'string' && v.trim().length > 0;
}

try { resolveCommandContext(opts, { requireCompany: true }); }
catch (err) {
  const msg = err instanceof Error ? err.message : '';
  if (msg.startsWith('Company ID is required.')) {
    console.error('Set a company: paperclipai context set --company-id cmp_xxx  (or pass --company-id / export PAPERCLIP_COMPANY_ID)');
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Any command marked requireCompany (e.g. `agent local-cli`, and other company-scoped subcommands) invoked without --company-id, without PAPERCLIP_COMPANY_ID exported, and without a companyId set in the current context profile via `paperclipai context set`.

Common situations: First run of a company-scoped command before configuring context. Multiple companies and the user forgot to select one. CI runner lacking PAPERCLIP_COMPANY_ID. Profile switched away from one that had companyId.

Related errors

• Failed to parse JSON at ${filePath}: ${err instanceof Error
• Agent not found: ${agentRef}
• Invalid config at ${filePath}: ${formatValidationError(parse
• Agent not found: ${agentRef}
• --payload must be a JSON object

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