{"record":{"id":"c9bc302af073a48f","repo":"paperclipai/paperclip","slug":"use-only-one-of-value-or-value-env","errorCode":null,"errorMessage":"Use only one of --value or --value-env.","messagePattern":"Use only one of --value or --value-env\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/secrets.ts","lineNumber":196,"sourceCode":"  const next: AgentEnvConfig = { ...(env as Record<string, EnvBinding>) };\n  for (const [envKey, secretId] of secretIdByEnvKey) {\n    next[envKey] = {\n      type: \"secret_ref\",\n      secretId,\n      version: \"latest\",\n    };\n  }\n  return next;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | null {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) return null;\n  return value as Record<string, unknown>;\n}\n\nfunction readValueFromOptions(opts: { value?: string; valueEnv?: string }): string {\n  if (opts.value !== undefined && opts.valueEnv !== undefined) {\n    throw new Error(\"Use only one of --value or --value-env.\");\n  }\n  if (opts.valueEnv !== undefined) {\n    const value = process.env[opts.valueEnv];\n    if (!value) throw new Error(`Environment variable ${opts.valueEnv} is empty or unset.`);\n    return value;\n  }\n  if (opts.value !== undefined) return opts.value;\n  throw new Error(\"Secret value is required. Pass --value or --value-env.\");\n}\n\nfunction renderDeclaration(input: CompanyPortabilityEnvInput): Record<string, unknown> {\n  const scope = input.agentSlug\n    ? `agent:${input.agentSlug}`\n    : input.projectSlug\n      ? `project:${input.projectSlug}`\n      : \"company\";\n  return {\n    key: input.key,","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/secrets.ts#L178-L214","documentation":"`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.","triggerScenarios":"Invoking a secret value command with both `--value <v>` and `--value-env <NAME>` at once (e.g. `secrets set ... --value x --value-env Y`).","commonSituations":"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.","solutions":["Provide exactly one source: either `--value <literal>` or `--value-env <NAME>`, not both","In scripts, use parameter expansion to pick one: `${VALUE:+--value \"$VALUE\"}` or `${VALUE_ENV:+--value-env \"$VALUE_ENV\"}`"],"exampleFix":"# before\npaperclipai secrets set ... --value secret --value-env SECRET_VALUE\n# after\npaperclipai secrets set ... --value-env SECRET_VALUE","handlingStrategy":"validation","validationCode":"function assertSingleValueSource(opts: { value?: string; valueEnv?: string }): void {\n  if (opts.value !== undefined && opts.valueEnv !== undefined) {\n    throw new Error(\"Pass either --value or --value-env, not both.\");\n  }\n}\nassertSingleValueSource(opts);","typeGuard":"function hasExactlyOneValueSource(opts: { value?: string; valueEnv?: string }): opts is { value: string } | { valueEnv: string } {\n  return (opts.value !== undefined) !== (opts.valueEnv !== undefined);\n}","tryCatchPattern":null,"preventionTips":["Treat --value and --value-env as mutually exclusive alternatives","In scripts, branch on which source is available before adding the flag","Document the mutual exclusion in command wrappers"],"tags":["cli","secrets","validation","mutual-exclusion"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}