Skip to content

Runtime environment-variable auth hints print only POSIX export KEY=... syntax, which fails in PowerShell and cmd.exe #5152

Description

@DamienStevens

Filed by /printing-press-retro from a retro of an 84-CLI MSP connector fleet. Reproduced on main at 5a59a797 (2026-10-21) with the minimal spec below.

Summary

Every runtime auth hint that tells the user to set an environment variable (API-key, bearer, Basic and client-credentials setup text in auth errors, auth status, auth setup, doctor's auth_hint and MCP tool errors) prints only export NAME="...". Hints that point at a command instead (browser login, auth set-token, service-account files) are not affected. On Windows that line does nothing useful in PowerShell (export is not a command) or in cmd.exe. The hints are runtime strings, so the binary knows which OS it is on, but always prints the POSIX form. #5032 fixed the same gap in the README's paths; the runtime hints were not covered.

Where to look

  • Component: generator
  • Issue type: bug
  • Likely area: internal/generator/generator.go (authSetupHint), internal/generator/templates/auth_simple.go.tmpl, auth_client_credentials.go.tmpl, client.go.tmpl, doctor.go.tmpl, skill.md.tmpl
  • Triggered when: an environment-variable auth hint is printed by a printed CLI running on Windows.

What we observed

At 5a59a797:

  • generator.go:2173-2232 (authSetupHint) builds Set your API key with: export %s="...", Set it with: export ..., Set credentials with: export ...; the result is baked into the generated Go as a string literal.
  • Literal export {{...}}= lines in templates: auth_simple.go.tmpl:237, :246, :263, :271, :537, :551, :556; auth_client_credentials.go.tmpl:302, :304; client.go.tmpl:399, :1844, :1864, :3673, :3694; doctor.go.tmpl:398.

Minimal spec (the same three-operation API-key spec as our related reports):

openapi: 3.0.3
info: {title: Repro Kit, version: 1.0.0}
servers: [{url: "https://api.example.com"}]
security: [{apiKey: []}]
components: {securitySchemes: {apiKey: {type: apiKey, in: header, name: X-API-Key}}}
paths:
  /v2/devices:
    get:
      operationId: listDevices
      tags: [devices]
      parameters: [{name: pageSize, in: query, schema: {type: integer}}]
      responses: {'200': {description: ok, content: {application/json: {schema: {type: array, items: {type: object, properties: {id: {type: integer}, systemName: {type: string}}}}}}}}
  /v2/devices/{id}:
    get:
      operationId: getDevice
      tags: [devices]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      responses: {'200': {description: ok, content: {application/json: {schema: {type: object, properties: {id: {type: integer}, systemName: {type: string}}}}}}}
  /v2/devices/{id}/retire:
    post:
      operationId: retireDevice
      tags: [devices]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody: {required: false, content: {application/json: {schema: {type: object, properties: {reason: {type: string}, dry_run: {type: boolean, description: Set true to preview the retire without performing it}}}}}}
      responses: {'200': {description: ok, content: {application/json: {schema: {type: object, properties: {status: {type: string}}}}}}}

With no credential configured:

$ snipkit-pp-cli auth setup
No setup URL is configured for this CLI; check the API's docs.

Then set:
  export SNIPKIT_API_KEY="your-token-here"
  echo "$TOKEN" | snipkit-pp-cli auth set-token

$ snipkit-pp-cli auth status
Not authenticated

Set your token:
  export SNIPKIT_API_KEY="your-token-here"
  echo "$TOKEN" | snipkit-pp-cli auth set-token
Error: no credentials configured

The same binary has 14 runtime export SNIPKIT_API_KEY="your-token-here" sites across internal/cli/auth.go, doctor.go, helpers.go, internal/client/client.go and internal/mcp/tools.go, and no PowerShell form anywhere in the Go code. Its README.md has a PowerShell twin (2 lines); its SKILL.md has none. We did not run the binaries on Windows for this report; the failure follows from PowerShell having no export command and cmd.exe using set.

In our fleet, 82 of 84 printed CLIs ship 858 such hint lines between them; three carry a downstream hand-fix that adds the PowerShell form.

Suspected root cause

Certain. Hint text is composed at generate time as a single POSIX string, with no runtime OS branch.

Suggested direction

  • Emit one small generated helper, for example cliutil.EnvAssignHint(name, placeholder string) string, that returns $env:NAME = "placeholder" when runtime.GOOS == "windows" and export NAME="placeholder" otherwise, and have authSetupHint output call it instead of baking the string.
  • For MCP tool errors and doctor --json auth_hint, where the caller's shell is unknown, include both forms (or a structured {env_var, placeholder} field next to the prose).
  • Add the PowerShell twin to the SKILL.md auth section, as the README already has.

Acceptance criteria

  • positive: a Windows build prints $env:SNIPKIT_API_KEY = "your-token-here" in every runtime hint; doctor --json carries both forms or the structured field.
  • negative: macOS/Linux builds print exactly today's text.

Frequency

every printed CLI with credential auth

Complexity

small

Dependencies

None.

Related issues


Generated by /printing-press-retro · CLI Printing Press

Activity

  1. added
    bugSomething isn't working
    source:retroIssue produced by /printing-press-retro; systemic Printing Press finding
    priority:P2Medium priority: meaningful recurring defect or capability gap
    surface:authCredential capture, sessions, cookies, tokens, and auth diagnostics
    on Oct 22, 2026
  2. added a commit that references this issue on Oct 23, 2026
    0930ee9
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingcomp:generatorpriority:P2Medium priority: meaningful recurring defect or capability gapsource:retroIssue produced by /printing-press-retro; systemic Printing Press findingsurface:authCredential capture, sessions, cookies, tokens, and auth diagnostics

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions