paperclipai/paperclip · error · Error

Use only one of --value or --value-env.

Error message

Use only one of --value or --value-env.

What it means

`readValueFromOptions` resolves a secret value from either `--value` (literal) or `--value-env` (env var name). Passing both is ambiguous, so it throws immediately, before reading any environment. This is a mutual-exclusion guard for secret set/create value input.

Source

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

  const next: AgentEnvConfig = { ...(env as Record<string, EnvBinding>) };
  for (const [envKey, secretId] of secretIdByEnvKey) {
    next[envKey] = {
      type: "secret_ref",
      secretId,
      version: "latest",
    };
  }
  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,

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Provide exactly one source: either `--value <literal>` or `--value-env <NAME>`, not both
2. In scripts, use parameter expansion to pick one: `${VALUE:+--value "$VALUE"}` or `${VALUE_ENV:+--value-env "$VALUE_ENV"}`

Example fix

# before
paperclipai secrets set ... --value secret --value-env SECRET_VALUE
# after
paperclipai secrets set ... --value-env SECRET_VALUE

function assertSingleValueSource(opts: { value?: string; valueEnv?: string }): void {
  if (opts.value !== undefined && opts.valueEnv !== undefined) {
    throw new Error("Pass either --value or --value-env, not both.");
  }
}
assertSingleValueSource(opts);

function hasExactlyOneValueSource(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 both `--value <v>` and `--value-env <NAME>` at once (e.g. `secrets set ... --value x --value-env Y`).

Common situations: A script template that conditionally adds flags but ended up setting both; copy-pasting an example that included both options; misunderstanding that the two are alternatives.

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,
• Environment variable ${opts.valueEnv} is empty or unset.
• Secret value is required. Pass --value or --value-env.

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