ANTHROPIC_API_KEY is required in the CLI process environment

Error message

ANTHROPIC_API_KEY is required in the CLI process environment

What it means

`validateManagedAgentSetup` reads `ANTHROPIC_API_KEY` from the CLI process environment and throws this when it is absent or blank. The Managed Agents beta calls Anthropic's API directly from the CLI, so a key in the local process env is mandatory; a key stored only as a Paperclip secret is not sufficient for setup.

Source

Thrown at cli/src/commands/managed-agent.ts:70

function record(value: unknown): Record<string, unknown> {
  return value && typeof value === "object" && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
}

function required(value: string | undefined, label: string): string {
  const normalized = value?.trim() ?? "";
  if (!normalized) throw new Error(`${label} is required`);
  return normalized;
}

export function validateManagedAgentSetup(
  options: ManagedAgentSetupOptions,
  env: NodeJS.ProcessEnv = process.env,
): ValidatedSetup {
  const anthropicApiKey = env.ANTHROPIC_API_KEY?.trim();
  if (!anthropicApiKey) {
    throw new Error("ANTHROPIC_API_KEY is required in the CLI process environment");
  }
  if (!options.acknowledgeRetention) {
    throw new Error(
      "Pass --acknowledge-retention to enable the stateful beta Managed Agents service",
    );
  }

  const profileKey = required(options.profileKey, "--profile-key");
  const displayName = required(options.displayName, "--display-name");
  const apiKeySecretId = required(options.apiKeySecretId, "--api-key-secret-id");
  const model = required(options.model, "--model");
  if (model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {
    throw new Error(
      `--model must be the qualified Managed Agents model ${CLAUDE_MANAGED_QUALIFIED_MODEL}`,
    );
  }
  if (!UUID_RE.test(apiKeySecretId)) {
    throw new Error("--api-key-secret-id must be a UUID");

View on GitHub (pinned to 5716fe907e)

Solutions

Export the key before running: export ANTHROPIC_API_KEY=sk-ant-...
Pass it inline: ANTHROPIC_API_KEY=sk-ant-... paperclip managed-agent ...
If using a .env file, ensure it is actually loaded into the process (e.g. with dotenv-cli), not just present on disk
Verify with `printenv ANTHROPIC_API_KEY` in the same shell that runs the CLI

Example fix

// before
$ paperclip managed-agent setup ...
// Error: ANTHROPIC_API_KEY is required in the CLI process environment
// after
$ export ANTHROPIC_API_KEY=sk-ant-...
$ paperclip managed-agent setup ...

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.ANTHROPIC_API_KEY?.trim()) {
  throw new Error("Set ANTHROPIC_API_KEY in the environment before running managed-agent commands");
}

Type guard

function hasAnthropicKey(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { ANTHROPIC_API_KEY: string } {
  return typeof env.ANTHROPIC_API_KEY === "string" && env.ANTHROPIC_API_KEY.trim().length > 0;
}

Try / catch

try {
  await runCommand();
} catch (err) {
  if (err instanceof Error && err.message.includes("ANTHROPIC_API_KEY is required")) {
    console.error("Export ANTHROPIC_API_KEY=sk-ant-... and retry"); process.exitCode = 1;
  } else throw err;
}

Prevention

Export ANTHROPIC_API_KEY in shell profiles or CI secret env, not just .env files on disk
Use dotenv-cli or similar to inject .env values into the actual process
Verify with `printenv ANTHROPIC_API_KEY` in the same shell that runs the CLI
Use the exact variable name; do not alias to ANTHROPIC_API_TOKEN

When it happens

Trigger: Running any managed-agent command (setup, probe, etc.) in a shell where ANTHROPIC_API_KEY is unset, empty, or whitespace-only; invoking validateManagedAgentSetup with a custom `env` object that lacks the key; running under CI/schedulers that sanitize the environment.

Common situations: New machine or container without the env var exported; `.env` files not loaded into the process environment; using a different var name like ANTHROPIC_API_TOKEN; dotenv loaded in a subshell but not the one running the CLI.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@5716fe907e (2026-09-02). Data as JSON: /api/errors/3c36941bb45271ae. Report an issue: GitHub.