@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/CLI_GRAMMAR_CREDENTIALS.md

@@ -0,0 +1,632 @@
+# CLI Grammar: Credentials
+
+> Defines the nexus CLI interface for credential management.
+>
+> **Scope:** This document covers credential storage, retrieval, and account management. Connector setup guides are in CLI_GRAMMAR_SKILLS.md.
+
+## Design Principles
+
+1. **No plaintext secrets** - Credentials are stored in secure backends (Keychain, 1Password), never in plain files.
+
+2. **CLI is the gateway** - All credential operations go through nexus CLI. `index.json` is a cache; CLI rebuilds from the tree.
+
+3. **Pointers, not secrets** - Credential files contain metadata + retrieval commands, not actual secrets.
+
+4. **Agent-friendly** - Both interactive and non-interactive (flag-based) flows supported.
+
+5. **Account = real identifier** - Account names are emails or usernames, not placeholders like "personal".
+
+---
+
+## Credential File Structure
+
+```
+state/credentials/
+├── {service}/
+│   ├── config.json                    # Shared config (optional, e.g., OAuth client)
+│   └── accounts/
+│       └── {account}/                 # Email or username
+│           └── auth/
+│               └── {type}.json        # api-key.json, oauth.json, token.json
+```
+
+**Index is cache-only** — The CLI walks the tree to discover credentials, then writes `index.json` as a cache.
+
+### Credential File Schema
+
+Each credential file contains metadata and a retrieval command:
+
+```json
+// state/credentials/anthropic/accounts/tyler@anthropic.com/auth/api-key.json
+{
+  "id": "anthropic-tyler@anthropic.com-api-key",
+  "type": "api-key",
+  "service": "anthropic",
+  "account": "tyler@anthropic.com",
+  "owner": "user",
+  "created": "2026-01-12T10:00:00Z",
+  "lastVerified": "2026-01-12T10:00:00Z",
+  
+  "storage": {
+    "provider": "keychain",
+    "command": "security find-generic-password -s nexus.anthropic.tyler@anthropic.com -a api_key -w"
+  }
+}
+```
+
+For 1Password:
+```json
+{
+  "storage": {
+    "provider": "1password",
+    "command": "op read \"op://Nexus/Anthropic API Key/api_key\""
+  }
+}
+```
+
+For environment variable (nexus doesn't store, just checks):
+```json
+{
+  "storage": {
+    "provider": "env",
+    "var": "ANTHROPIC_API_KEY"
+  }
+}
+```
+
+For external command (raw string):
+```json
+{
+  "storage": {
+    "provider": "external",
+    "command": "op read \"op://Nexus/Anthropic API Key/api_key\""
+  }
+}
+```
+
+For external command (JSON output):
+```json
+{
+  "storage": {
+    "provider": "external",
+    "command": "security find-generic-password -s \"Claude Code-credentials\" -w",
+    "format": "json",
+    "jsonPath": "claudeAiOauth.accessToken"
+  }
+}
+```
+
+The `command` field must print the secret (raw or JSON). Nexus reads it directly.
+
+---
+
+## Storage Providers
+
+| Provider | Platform | Setup Required | Notes |
+|----------|----------|----------------|-------|
+| **keychain** | macOS | None | Uses login keychain, encrypted by OS |
+| **1password** | All | 1Password CLI (`op`) | Full password manager, syncs across devices |
+| **env** | All | Manual | Nexus reads from env var; you set/persist it |
+| **external** | All | Depends | Command that outputs secret (raw or JSON) |
+
+**Default:** `keychain` on macOS; otherwise specify `env` or `external`.
+
+### macOS Keychain
+
+Uses the `security` command to store/retrieve:
+```bash
+# Store
+security add-generic-password -s nexus.anthropic.tyler@anthropic.com -a api_key -w "sk-ant-xxx"
+
+# Retrieve
+security find-generic-password -s nexus.anthropic.tyler@anthropic.com -a api_key -w
+
+# Delete
+security delete-generic-password -s nexus.anthropic.tyler@anthropic.com -a api_key
+```
+
+### 1Password
+
+Uses the `op` CLI:
+```bash
+# Store (create item)
+op item create --category="API Credential" --title="Anthropic API Key" --vault="Nexus" api_key="sk-ant-xxx"
+
+# Retrieve
+op read "op://Nexus/Anthropic API Key/api_key"
+
+# Delete
+op item delete "Anthropic API Key" --vault="Nexus"
+```
+
+---
+
+## Command Reference
+
+### `nexus credential list`
+
+List all credentials.
+
+```bash
+nexus credential list                      # All credentials
+nexus credential list --service google     # Filter by service
+nexus credential list --owner user         # Filter by owner
+nexus credential list --owner agent:echo   # Agent's credentials
+nexus credential list --json               # JSON output
+```
+
+**Output:**
+```
+Credentials (5 total)
+
+google (2 accounts):
+  ● tyler@gmail.com (oauth) - owner: user
+  ● echo@nexus.bot (oauth) - owner: agent:echo
+
+anthropic (1 account):
+  ● tyler@anthropic.com (api-key) - owner: user
+
+openai (1 account):
+  ● tyler@openai.com (api-key) - owner: user
+
+brave-search (1 account):
+  ● tyler@brave.com (api-key) - owner: user
+```
+
+### `nexus credential add`
+
+Add a new credential. Supports both interactive and non-interactive modes.
+
+**Interactive:**
+```bash
+nexus credential add
+```
+
+```
+? Service: anthropic
+? Account (email/username): tyler@anthropic.com
+? Credential type: api-key
+? Owner (user / agent:<name>): user
+? Storage provider:
+ > keychain (macOS Keychain - secure, no setup)
+   1password (requires op CLI)
+    env (read from env var)
+    external (command that outputs secret)
+
+? Enter your API key: sk-ant-xxxxx
+
+Storing in macOS Keychain...
+✓ Stored: nexus.anthropic.tyler@anthropic.com
+
+Created: state/credentials/anthropic/accounts/tyler@anthropic.com/auth/api-key.json
+
+Test with: nexus credential verify anthropic/tyler@anthropic.com
+```
+
+**Non-interactive (for agents):**
+```bash
+nexus credential add \
+  --service anthropic \
+  --account tyler@anthropic.com \
+  --type api-key \
+  --owner user \
+  --storage keychain \
+  --value "sk-ant-xxxxx"
+```
+
+**Flags:**
+- `--service` - Service name (anthropic, google, etc.)
+- `--account` - Account identifier (email or username)
+- `--type` - Credential type (api-key, oauth, token)
+- `--owner` - Owner (user, agent:name)
+- `--storage` - Storage provider (keychain, 1password, env, external)
+- `--value` - Secret value for keychain storage
+- `--env-var` - For env storage, which variable to check
+- `--command` - External command that prints the secret
+- `--format` - External output format (raw|json)
+- `--json-path` - JSON path in external output
+- `--vault` - For 1password, which vault
+- `--item` - For 1password, item name
+
+### `nexus credential import`
+
+Import external CLI credentials into the Nexus store (no secrets stored on disk).
+
+```bash
+nexus credential import claude-cli
+nexus credential import codex-cli
+```
+
+Options:
+- `--account` - Override account name (default: `claude-cli` / `codex-cli`)
+- `--owner` - Owner (user, agent:name)
+- `--force` - Overwrite existing record
+
+### `nexus credential verify`
+
+Test that a credential can be retrieved and works.
+
+```bash
+nexus credential verify anthropic                           # Verify all anthropic accounts
+nexus credential verify anthropic/tyler@anthropic.com       # Verify specific account
+nexus credential verify --all                               # Verify all credentials
+nexus credential verify --json                              # JSON output
+```
+
+**Output:**
+```
+Verifying: anthropic/tyler@anthropic.com
+
+✓ Storage accessible (keychain)
+✓ Secret retrieved successfully
+✓ API test passed (valid key)
+
+Credential is working.
+```
+
+### `nexus credential remove`
+
+Remove a credential.
+
+```bash
+nexus credential remove anthropic/tyler@anthropic.com
+nexus credential remove anthropic/tyler@anthropic.com --keep-secret  # Keep in keychain, remove pointer
+```
+
+**Output:**
+```
+Removing: anthropic/tyler@anthropic.com
+
+? Also remove from keychain? (y/n) y
+
+✓ Removed from keychain
+✓ Removed credential file
+
+Credential removed.
+```
+
+### `nexus credential get`
+
+Retrieve a credential value (for scripts/agents).
+
+```bash
+nexus credential get anthropic/tyler@anthropic.com
+# Output: sk-ant-xxxxx (just the value, for piping)
+
+# Or with metadata
+nexus credential get anthropic/tyler@anthropic.com --json
+
+# Or show the record instead of the value
+nexus credential get anthropic/tyler@anthropic.com --record --json
+```
+
+### `nexus credential update`
+
+Update credential metadata (not the secret itself).
+
+```bash
+nexus credential update anthropic/tyler@anthropic.com --owner agent:echo
+```
+
+To update the actual secret, use `add` with `--force`:
+```bash
+nexus credential add --service anthropic --account tyler@anthropic.com --value "new-key" --force
+```
+
+---
+
+## Account Ownership
+
+### `nexus accounts list`
+
+List accounts grouped by owner.
+
+```bash
+nexus accounts list                    # All accounts
+nexus accounts list --user             # User's accounts
+nexus accounts list --agent echo       # Specific agent's accounts
+nexus accounts list --json             # JSON output
+```
+
+**Output:**
+```
+Accounts by Owner
+
+User:
+  google/tyler@gmail.com
+  anthropic/tyler@anthropic.com
+  openai/tyler@openai.com
+  brave-search/tyler@brave.com
+
+Agent (echo):
+  google/echo@nexus.bot
+  discord/echo-bot
+```
+
+---
+
+## Environment Variable Detection
+
+Nexus can detect API keys in environment variables and offer to import them securely.
+
+### `nexus credential scan`
+
+Scan for environment variables containing credentials.
+
+```bash
+nexus credential scan                  # Scan known vars only
+nexus credential scan --deep           # Scan ALL env vars for patterns
+nexus credential scan --import         # Interactive import
+nexus credential scan --import --auto  # Auto-import to keychain (uses 'unknown' for accounts)
+```
+
+### Standard Scan (Known Variables)
+
+Checks a predefined list of common env var names:
+
+**Known variables:**
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`
+- `BRAVE_API_KEY`
+- `GITHUB_TOKEN`
+- `DISCORD_BOT_TOKEN`
+- `SLACK_BOT_TOKEN`
+- `FIRECRAWL_API_KEY`
+- `APIFY_API_TOKEN`
+- `ELEVENLABS_API_KEY`
+- ... (extensible via connector frontmatter)
+
+**Output:**
+```
+Scanning environment for known API keys...
+
+Found (3):
+  ✓ ANTHROPIC_API_KEY (sk-ant-...xxxx)
+  ✓ OPENAI_API_KEY (sk-...xxxx)
+  ✓ GEMINI_API_KEY (AI...xxxx)
+
+Not found (2):
+  ○ BRAVE_API_KEY
+  ○ DISCORD_BOT_TOKEN
+
+Run 'nexus credential scan --import' to save to keychain.
+```
+
+### Deep Scan (All Environment Variables)
+
+Scans ALL env vars looking for patterns that indicate credentials.
+
+```bash
+nexus credential scan --deep
+```
+
+**Asks for confirmation first:**
+```
+Deep scan will examine ALL environment variables to find potential credentials.
+This is useful if you have keys under non-standard names.
+
+? Proceed with deep scan? (y/n) y
+```
+
+**Name patterns detected:**
+- `*_API_KEY`, `*_TOKEN`, `*_SECRET`
+- `*_PASSWORD`, `*_AUTH`, `*_CREDENTIAL`
+
+**Value patterns detected:**
+- `sk-ant-*` → Anthropic
+- `sk-*` → OpenAI
+- `xoxb-*`, `xoxp-*` → Slack
+- `ghp_*`, `gho_*`, `github_pat_*` → GitHub
+- Long alphanumeric strings (40+ chars) → Generic secret
+
+**Output:**
+```
+Deep scanning environment...
+
+Known variables:
+  ✓ ANTHROPIC_API_KEY (sk-ant-...xxxx)
+  ✓ OPENAI_API_KEY (sk-...xxxx)
+
+Discovered (pattern match):
+  ? MY_CLAUDE_KEY - looks like Anthropic key (sk-ant-...xxxx)
+  ? WORK_GITHUB_TOKEN - looks like GitHub PAT (ghp_...xxxx)
+  ? ACME_API_SECRET - generic secret pattern (Kj8x...xxxx)
+
+Run 'nexus credential scan --deep --import' to review and import.
+```
+
+### Import Flow
+
+```bash
+nexus credential scan --import         # Import known vars
+nexus credential scan --deep --import  # Import known + discovered
+```
+
+**Interactive import:**
+```
+$ nexus credential scan --import
+
+Found: ANTHROPIC_API_KEY (sk-ant-...xxxx)
+
+? Import to nexus credentials? (y/n) y
+? Account (email/username, or 'unknown'): tyler@anthropic.com
+? Owner: user
+
+✓ Stored in keychain
+✓ Created: state/credentials/anthropic/accounts/tyler@anthropic.com/auth/api-key.json
+
+Found: OPENAI_API_KEY (sk-...xxxx)
+
+? Import to nexus credentials? (y/n) y
+? Account (email/username, or 'unknown'): unknown
+? Owner: user
+
+✓ Stored in keychain
+✓ Created: state/credentials/openai/accounts/unknown/auth/api-key.json
+
+Import complete. 2 credentials added.
+
+Note: For 'unknown' accounts, update later with:
+  nexus credential update openai/unknown --account your@email.com
+```
+
+**Deep scan import (includes discovered vars):**
+```
+$ nexus credential scan --deep --import
+
+[... known vars first ...]
+
+Discovered: MY_CLAUDE_KEY (sk-ant-...xxxx)
+Detected pattern: Anthropic API key
+
+? Is this an Anthropic credential? (y/n) y
+? Account (email/username): tyler@anthropic.com
+? Import to keychain? (y/n) y
+
+✓ Imported as anthropic/tyler@anthropic.com
+
+Discovered: WORK_GITHUB_TOKEN (ghp_...xxxx)
+Detected pattern: GitHub PAT
+
+? Is this a GitHub credential? (y/n) y
+? Account (email/username): tyler-work
+? Import to keychain? (y/n) y
+
+✓ Imported as github/tyler-work
+```
+
+### Auto Import
+
+For quick onboarding, auto-import uses `unknown` for account names:
+
+```bash
+nexus credential scan --import --auto
+```
+
+```
+Auto-importing credentials to keychain...
+
+✓ ANTHROPIC_API_KEY → anthropic/unknown
+✓ OPENAI_API_KEY → openai/unknown
+✓ GEMINI_API_KEY → gemini/unknown
+
+Imported 3 credentials.
+
+Update account names later with:
+  nexus credential update anthropic/unknown --account your@email.com
+```
+
+---
+
+## Configuration
+
+### Default Storage Provider
+
+```bash
+nexus config set credential-store keychain    # Default for new credentials
+nexus config set credential-store 1password
+nexus config get credential-store
+```
+
+### 1Password Settings
+
+```bash
+nexus config set 1password-vault Nexus        # Default vault
+nexus config get 1password-vault
+```
+
+---
+
+## Integration with Connectors
+
+When running `nexus connector setup <name>`, the connector's setup guide walks through creating credentials:
+
+```bash
+$ nexus connector setup google-oauth
+
+# ... OAuth flow happens ...
+
+# Under the hood, this calls:
+nexus credential add \
+  --service google \
+  --account tyler@gmail.com \
+  --type oauth \
+  --owner user \
+  --storage keychain \
+  --value "<oauth-token-json>"
+```
+
+Connectors know which credentials they need. Tools reference connectors, and connectors reference credentials.
+
+```
+Tool (gog) 
+  → requires Connector (google-oauth)
+    → requires Credential (google/tyler@gmail.com/oauth)
+      → stored in Keychain
+```
+
+---
+
+## Examples
+
+### Agent checking available credentials
+
+```bash
+# What credentials do I have?
+nexus credential list --json
+
+# Can I use anthropic?
+nexus credential verify anthropic
+
+# Get the key for a script
+API_KEY=$(nexus credential get anthropic/tyler@anthropic.com)
+```
+
+### User setting up from scratch
+
+```bash
+# Scan what's already in env
+nexus credential scan --import
+
+# Add a new one manually
+nexus credential add
+
+# Verify everything works
+nexus credential verify --all
+```
+
+### Migrating env vars to keychain
+
+```bash
+# See what's in env
+nexus credential scan
+
+# Import all to keychain
+nexus credential scan --import --auto
+
+# Now you can remove from .zshrc/.bashrc
+```
+
+---
+
+## Security Notes
+
+1. **Secrets never in files** - Credential files contain pointers, not secrets.
+
+2. **Keychain is OS-encrypted** - macOS Keychain uses hardware encryption.
+
+3. **1Password requires unlock** - May prompt for authentication.
+
+4. **Env vars are visible** - `ps` can show env vars; keychain is safer.
+
+5. **Agent access** - Agents can retrieve credentials they own or shared credentials.
+
+---
+
+## Related Documents
+
+- [CLI_GRAMMAR_SKILLS.md](./CLI_GRAMMAR_SKILLS.md) - Skill/connector commands
+- [STATE_ARCHITECTURE.md](./STATE_ARCHITECTURE.md) - Full state structure
+- [ENTITY_MODEL.md](./ENTITY_MODEL.md) - Connector definitions
+- CLI_GRAMMAR_ONBOARDING.md - Onboarding commands (TBD)