Auth command

The auth command provides subcommands for managing API key authentication and storage. Currently, it supports the set-key subcommand for securely storing API keys for use with other SignotaurTool commands.

auth set-key

Securely stores an API key for use with SignotaurTool commands. This command bootstraps API key storage from various sources and can optionally verify the key with the server before storing it.

Usage

SignotaurTool.exe auth set-key [options]

Options

Input Source (Required - choose one)

Exactly one of the following input options must be specified (they are mutually exclusive).

  • --fs, --from-stdin

    Read API key from standard input. Recommended when running interactively in a terminal, as it prevents the API key from appearing in shell history or process lists.

  • --fe, --from-env <Name>

    Read API key from environment variable (e.g., MY_API_KEY). Useful for reading keys from CI/CD environment variables.

  • -a, --api-key <APIKey>

    API key value provided directly. Warning: This method is less secure as the key may appear in shell history or process lists.

Output Destination (Required - choose one)

Exactly one of the following output options must be specified (they are mutually exclusive).

  • --wk, --write-key-file <Path>

    Write API key to a plain text file (mutually exclusive with --write-env-file). The file will be created with secure permissions (Windows ACL owner-only read/write).

  • --we, --write-env-file <Path>

    Write API key to a dotenv file as SIGNOTAUR_API_KEY=<key> (mutually exclusive with --write-key-file).

  • --wn, --write-env-var-name <VarName>

    Variable name when writing to dotenv file (default: SIGNOTAUR_API_KEY). Only used with --write-env-file.

Optional Settings

  • --im, --if-missing

    Skip if destination file already exists (idempotent). This allows the command to be run safely multiple times without overwriting existing keys.

  • --vf, --verify

    Validate API key with server before storing. Requires --sign-server to be specified.

  • -s, --sign-server <URL>

    Signotaur server URL (required if --verify is used).

  • --au, --allow-untrusted

    Allow connecting to a Signotaur server bound to an untrusted or invalid certificate. Warning: This disables TLS certificate validation and should only be used in development or controlled environments.

Examples

  1. Store API key from stdin (recommended for interactive terminals):

    echo your-api-key-here | SignotaurTool.exe auth set-key --from-stdin --write-key-file %USERPROFILE%\.signotaur\api_key.txt

  2. Store API key from environment variable with verification:

    SignotaurTool.exe auth set-key --from-env MY_API_KEY --write-key-file %USERPROFILE%\.signotaur\api_key.txt --verify --sign-server https://signotaur.example.com

  3. Store API key to dotenv file:

    echo your-api-key-here | SignotaurTool.exe auth set-key --from-stdin --write-env-file .env

  4. Idempotent key storage (skip if file exists):

    echo your-api-key-here | SignotaurTool.exe auth set-key --from-stdin --write-key-file %USERPROFILE%\.signotaur\api_key.txt --if-missing

  5. Store API key with custom environment variable name:

    SignotaurTool.exe auth set-key --from-env MY_CUSTOM_KEY --write-env-file .env --write-env-var-name CUSTOM_API_KEY

Workflow

The auth set-key command is typically used as part of the initial setup or in CI/CD pipelines:

  1. Bootstrap - Obtain API key from Signotaur Web UI
  2. Store - Use auth set-key to securely store the key
  3. Use - Reference the stored key in subsequent sign or rotate-key commands via --api-key-file

Security Best Practices

  • ✓ Use --from-stdin for interactive terminal usage
  • ✓ Store keys with secure file permissions (Windows ACL owner-only)
  • ✓ Use --verify to validate keys before storing
  • ✓ Use --if-missing for idempotent CI/CD scripts
  • ✗ Avoid --api-key parameter in production (appears in shell history/process lists)
  • ✗ Never commit API key files to version control
  • ✗ Avoid --allow-untrusted except in development/controlled environments

Exit Codes

  • 0 (Success): API key stored successfully
  • 1 (Failure): General error (e.g., file I/O error, invalid arguments)
  • 2 (Verification Failed): API key verification with server failed (when using --verify)

See Also

  • Sign Command - Using stored API keys for signing
  • Rotate Key Command - Rotating API keys with overlapping validity
  • API Key Management - Complete CLI workflow guide
  • API Key Lifecycle - Conceptual overview and best practices