output-credentials-env-vars

What this skill does

# Credentials as Environment Variables

## When to Use This Skill

- Setting up `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` from encrypted credentials
- Wiring any credential path to a `process.env` variable automatically
- Migrating from plaintext `.env` secrets to encrypted credentials
- Understanding why an env var is being resolved at worker startup

## The `credential:` Convention

Any env var whose value starts with `credential:` is resolved from encrypted credentials at worker startup. The format is:

```
ENV_VAR_NAME=credential:<dot.path>
```

### Example `.env`

```bash
# These are resolved automatically from config/credentials.yml.enc
ANTHROPIC_API_KEY=credential:anthropic.api_key
OPENAI_API_KEY=credential:openai.api_key

# Any credential path works
MY_SERVICE_TOKEN=credential:my_service.token
DATABASE_URL=credential:postgres.url
```

### Encrypted credentials (`config/credentials.yml.enc`)

```yaml
anthropic:
  api_key: sk-ant-...        # → resolves ANTHROPIC_API_KEY

openai:
  api_key: sk-...            # → resolves OPENAI_API_KEY

my_service:
  token: tok_live_...        # → resolves MY_SERVICE_TOKEN

postgres:
  url: postgres://...        # → resolves DATABASE_URL
```

## How It Works

1. Worker loads `.env` via dotenv — `ANTHROPIC_API_KEY` = `"credential:anthropic.api_key"`
2. Worker loads all workflow activity files (importing `@outputai/credentials`)
3. Worker calls `runStartupHooks()` — `resolveCredentialRefs()` runs
4. `resolveCredentialRefs()` scans `process.env` for `credential:` prefix values
5. Each matching var is replaced with the actual decrypted credential value
6. `ANTHROPIC_API_KEY` is now `"sk-ant-..."` in `process.env`
7. LLM SDK reads it normally when the first workflow activity runs

## The `_env` Section in Credentials YAML

The credentials file can also declare the mapping directly in an `_env` section. New projects scaffold with this pre-configured:

```yaml
anthropic:
  api_key: sk-ant-...
openai:
  api_key: sk-...

_env:
  ANTHROPIC_API_KEY: anthropic.api_key
  OPENAI_API_KEY: openai.api_key
```

> **Note:** The `_env` section is metadata only — it documents the intended mapping but does not drive resolution. Resolution is driven by the `credential:` values in `.env`. Keep both in sync.

## Precedence Rules

Real env var values always take precedence. If `ANTHROPIC_API_KEY` is already set to a non-`credential:` value (e.g. from the shell or a CI secret), it is **never overwritten**:

```bash
# Real value — never touched by resolveCredentialRefs
ANTHROPIC_API_KEY=sk-ant-real-override

# Placeholder — gets replaced at startup
ANTHROPIC_API_KEY=credential:anthropic.api_key
```

This means you can override any credential ref at deploy time without changing files.

## Idempotency

After the first resolution, `ANTHROPIC_API_KEY` contains the real API key string — it no longer starts with `credential:`. Subsequent calls to `resolveCredentialRefs()` are no-ops for that variable.

## Setting Up the Convention

### Step 1: Initialize credentials (if not done)

```bash
npx output credentials init
npx output credentials edit   # Add anthropic.api_key, openai.api_key
```

### Step 2: Update `.env`

```bash
# Replace plaintext secrets with credential references
ANTHROPIC_API_KEY=credential:anthropic.api_key
OPENAI_API_KEY=credential:openai.api_key
```

### Step 3: Verify

Start the worker and look for the log line:

```
Startup hooks resolved env vars {"vars":["ANTHROPIC_API_KEY","OPENAI_API_KEY"]}
```

If the log line appears, credentials are wired correctly.

## Programmatic Access

If you need to call `resolveCredentialRefs()` outside of a worker context:

```typescript
import { resolveCredentialRefs } from '@outputai/credentials';

// Returns array of env var names that were resolved
const resolved = resolveCredentialRefs();
console.log('Resolved:', resolved);
// → ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]
```

## Verification Checklist

- [ ] `config/credentials.yml.enc` contains the target credential paths
- [ ] `.env` uses `credential:<path>` values for the relevant env vars
- [ ] Worker startup log shows `Startup hooks resolved env vars`
- [ ] First LLM workflow run succeeds (confirming `ANTHROPIC_API_KEY` is set correctly)
- [ ] Setting a real env var in the shell overrides the credential ref

## Related Skills

- `output-credentials-init` — Create the encrypted credentials file
- `output-credentials-edit` — Add/update credential values
- `output-dev-credentials` — Full credentials system reference