paperclipai/paperclip · error · Error

Secret value is required. Pass --value or --value-env.

Error message

Secret value is required. Pass --value or --value-env.

What it means

`readValueFromOptions` falls through both the `--value-env` and `--value` branches because neither option was provided (both `undefined`). It throws requiring at least one value source. This is the required-input guard for secret set/create commands.

Source

Thrown at cli/src/commands/client/secrets.ts:204

  return next;
}

function asRecord(value: unknown): Record<string, unknown> | null {
  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
  return value as Record<string, unknown>;
}

function readValueFromOptions(opts: { value?: string; valueEnv?: string }): string {
  if (opts.value !== undefined && opts.valueEnv !== undefined) {
    throw new Error("Use only one of --value or --value-env.");
  }
  if (opts.valueEnv !== undefined) {
    const value = process.env[opts.valueEnv];
    if (!value) throw new Error(`Environment variable ${opts.valueEnv} is empty or unset.`);
    return value;
  }
  if (opts.value !== undefined) return opts.value;
  throw new Error("Secret value is required. Pass --value or --value-env.");
}

function renderDeclaration(input: CompanyPortabilityEnvInput): Record<string, unknown> {
  const scope = input.agentSlug
    ? `agent:${input.agentSlug}`
    : input.projectSlug
      ? `project:${input.projectSlug}`
      : "company";
  return {
    key: input.key,
    scope,
    kind: input.kind,
    requirement: input.requirement,
    portability: input.portability,
    hasDefault: input.defaultValue !== null && input.defaultValue.length > 0,
    description: input.description,
  };
}

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Pass a literal: `--value <secret>`
2. Or read from the environment: `--value-env <NAME>` (after exporting it)
3. In scripts, fail fast when no value source is configured before invoking the command

Example fix

# before
paperclipai secrets set comp-1 DB_PASSWORD
# after
paperclipai secrets set comp-1 DB_PASSWORD --value-env DB_PASSWORD

function requireValueSource(opts: { value?: string; valueEnv?: string }): void {
  if (opts.value === undefined && opts.valueEnv === undefined) {
    throw new Error("Secret value is required. Pass --value or --value-env.");
  }
}
requireValueSource(opts);

function hasValueSource(opts: { value?: string; valueEnv?: string }): opts is { value: string } | { valueEnv: string } {
  return opts.value !== undefined || opts.valueEnv !== undefined;
}

When it happens

Trigger: Invoking a secret value command with neither `--value` nor `--value-env`, e.g. `secrets set <key>` with no value source.

Common situations: Assuming the command will prompt interactively (it does not); forgetting the value flag; a script that conditionally added the flag but the condition was false.

Related errors

• Environment variable ${envName} is empty or not set.
• Challenge secret is required. Pass --token or --token-env.
• Invalid --include value. Use one or more of: company,agents,
• Use only one of --value or --value-env.
• Environment variable ${opts.valueEnv} is empty or unset.

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