/output-dev-credentials

name: output-dev-credentials
description: Store and reference encrypted secrets in Output SDK workflows using @outputai/core/credentials. Use when integrating API keys, database passwords, or third-party tokens.
allowed-tools: [Read, Write, Edit, Bash, Glob]

Encrypted Credentials Management

Overview

The `@outputai/core/credentials` package provides encrypted secrets management for Output SDK workflows. It replaces `process.env` patterns with a structured, encrypted YAML-based system that supports scoped credentials with deep merging.

When to Use This Skill

• Adding API keys or tokens to a workflow
• Migrating from `process.env` to encrypted credentials
• Setting up per-workflow or per-environment secrets
• Debugging missing credential errors (`MissingCredentialError`, `MissingKeyError`)
• Configuring custom credential providers (Vault, AWS Secrets Manager)

Library API

Import

import { credentials } from '@outputai/core/credentials';

`credentials.get(path, defaultValue?)`

Safe read with optional default. Never throws.

// Returns value or undefined
const region = credentials.get('aws.region');

// Returns value or default
const region = credentials.get('aws.region', 'us-east-1');

`credentials.require(path)`

Strict read. Throws `MissingCredentialError` if not found.

const apiKey = credentials.require('anthropic.api_key');

Error Types

| Error | Thrown When | Fix | |-------|------------|-----| | `MissingCredentialError` | `credentials.require()` path not found | Add the credential via `output credentials edit` | | `MissingKeyError` | No decryption key available | Set `OUTPUT_CREDENTIALS_KEY` env var or create `.key` file | | `InvalidCredentialsKeyError` | Key doesn't match the encrypted file, or the file is corrupted | Use the key the file was encrypted with | | `MalformedCredentialsKeyError` | Key isn't exactly 64 hex characters | Check the key for typos, whitespace, or truncation |

All four extend `FatalError`, so a step that throws one fails without retries. A key error while resolving `credential:` env vars stops the worker at startup.

CLI Commands

# Initialize credentials (generates key + encrypted YAML template)
output credentials init                              # Global
output credentials init -e production                 # Environment-specific
output credentials init -w payment_processing         # Workflow-specific

# Edit credentials (decrypts, opens $EDITOR, re-encrypts on save)
output credentials edit                               # Global
output credentials edit -e production                  # Environment
output credentials edit -w payment_processing          # Workflow

# Show decrypted credentials (debugging)
output credentials show                               # Global
output credentials show -e development                 # Environment

# Set a single credential value (no editor needed)
output credentials set anthropic.api_key sk-ant-...    # Global
output credentials set stripe.key sk_live_... -w payment_processing # Workflow

# Get single credential value
output credentials get anthropic.api_key               # Global
output credentials get stripe.key -w payment_processing # Workflow

**Flags:**

• `-e` / `--environment`: Target environment (`production` or `development`, the only values the worker reads)
• `-w` / `--workflow`: Target a specific workflow
• `-f` / `--force`: `init` overwrites existing credentials; `edit` and `set` re-encrypt with the current key when it can't decrypt the file (discards existing values)
• `-y` / `--yes`: Skip the confirmation when `set` replaces a value of a different shape (`set` only)
• Note: `-e` and `-w` are mutually exclusive

Three-Tier Scope System

1. Global Credentials

config/credentials.yml.enc    # Encrypted YAML
config/credentials.key        # Decryption key (DO NOT COMMIT)

Key env var: `OUTPUT_CREDENTIALS_KEY`

2. Environment-Specific Credentials

config/credentials/production.yml.enc
config/credentials/production.key

Key env var: `OUTPUT_CREDENTIALS_KEY_PRODUCTION`

3. Per-Workflow Credentials

src/workflows/{name}/credentials.yml.enc
src/workflows/{name}/credentials.key

Key env var: `OUTPUT_CREDENTIALS_KEY_{WORKFLOW_NAME}` (uppercased)

Key Resolution Chain

For each scope, the key is resolved in order:

1. **Environment variable** (`OUTPUT_CREDENTIALS_KEY`, `OUTPUT_CREDENTIALS_KEY_{ENV}`, or `OUTPUT_CREDENTIALS_KEY_{WORKFLOW}`) 2. **Key file** on disk (e.g., `config/credentials.key`) 3. **Throws `MissingKeyError`** if neither found

Workflow credentials fall back to the global key if no workflow-specific key exists.

Credential Merging

When a workflow has its own credentials, they deep-merge over global credentials. Workflow values win at the same path:

# Global (config/credentials.yml.enc)
anthropic:
  api_key: sk-ant-global
aws:
  region: us-east-1

# Workflow (src/workflows/my_workflow/credentials.yml.enc)
anthropic:
  api_key: sk-ant-workflow-specific
stripe:
  secret_key: sk_live_workflow

# Merged result at runtime:
# anthropic.api_key  -> sk-ant-workflow-specific  (overridden by workflow)
# aws.region         -> us-east-1                 (from global)
# stripe.secret_key  -> sk_live_workflow           (added by workflow)

Migration from `process.env`

Before (old pattern)

import { createKyClient } from '@outputai/core/http';

const API_KEY = process.env.SERVICE_API_KEY || '';

const client = createKyClient({
  prefix: 'https://api.service.com',
  headers: { Authorization: `Bearer ${API_KEY}` }
});

After (credentials pattern)

import { createKyClient } from '@outputai/core/http';
import { credentials } from '@outputai/core/credentials';

const apiKey = credentials.require('service.api_key');

const client = createKyClient({
  prefix: 'https://api.service.com',
  headers: { Authorization: `Be