Vincent - Credentials

1. Check for Existing Keys

Before creating a new secret, check if one already exists:

npx @vincentai/cli@latest secret list --type CREDENTIALS

If a key is returned, use its id as the --key-id for subsequent commands. If no keys exist, create a new secret.

2. Create a Credentials Secret

npx @vincentai/cli@latest secret create --type CREDENTIALS --memo "Acme API credentials"

Returns keyId (use for all future commands), claimUrl (share with the user), and secretId.

After creating, tell the user:

> "Here is your credentials claim URL: . Use this to claim ownership and set the credential value at https://heyvincent.ai."

3. Set the Credential Value

Option A: User sets via dashboard (recommended)

The user claims the secret using the claim URL, then sets the credential value from the dashboard. This keeps the value completely out of the agent's hands.

Option B: Agent sets via CLI

For agent-first workflows where the agent has the credential (e.g. it obtained an API key from a service):

npx @vincentai/cli@latest secret set-value --key-id  --value '{"username": "alice", "password": "hunter2"}'

For simple string types (API_KEY, SSH_KEY, OAUTH_TOKEN):

npx @vincentai/cli@latest secret set-value --key-id  --value "sk-my-third-party-api-key"

4. Write to .env File

Once the value is set (by the user or the agent), use the CLI to write it to a .env file. The value is never printed to stdout.

# Write an API_KEY secret as an env var
npx @vincentai/cli@latest secret env --key-id  --env-var ACME_API_KEY
For CREDENTIALS: extract a specific field
npx @vincentai/cli@latest secret env --key-id  --env-var DB_PASSWORD --field password
Write to a specific path (default: ./.env)
npx @vincentai/cli@latest secret env --key-id  --env-var SERVICE_TOKEN --path ./config/.env

The command outputs a confirmation JSON (without the value) so the agent knows it succeeded:

{
  "written": "ACME_API_KEY",
  "path": "/path/to/.env",
  "type": "API_KEY"
}

Flags:

| Flag | Required | Description | |---|---|---| | --env-var | Yes | Environment variable name (e.g. MY_API_KEY) | | --path | No | Path to .env file (default: ./.env) | | --key-id | No | API key ID (auto-discovered if only one credential key exists) | | --field | No | For CREDENTIALS type: extract a specific JSON field instead of writing the full JSON |

Behavior:

5. Use in Your Application

Your application reads the .env file normally:

# Node.js with dotenv
require('dotenv').config()
const apiKey = process.env.ACME_API_KEY
Python with python-dotenv
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv('ACME_API_KEY')