### Install AgentSecrets

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Installation instructions for macOS, npm, PyPI, and from source.

```bash
brew install the-17/tap/agentsecrets
```

```bash
npm install -g @the-17/agentsecrets
```

```bash
pip install agentsecrets
```

```bash
git clone https://github.com/The-17/agentsecrets
cd agentsecrets
go build -o agentsecrets ./cmd/agentsecrets
```

--------------------------------

### Quick Start

Source: https://github.com/the-17/agentsecrets/blob/main/docs/CONTRIBUTING.md

Instructions for setting up the AgentSecrets project, including forking the repository, installing Go, downloading dependencies, and running the CLI.

```bash
# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/agentsecrets
cd agentsecrets

# Install Go (1.21+)
# macOS: brew install go
# Linux: snap install go --classic
# Windows: Download from https://go.dev/dl/

# Download dependencies
go mod download

# Run the CLI
go run cmd/agentsecrets/main.go --help

# Run tests
go test ./...

# Build binary
go build -o agentsecrets cmd/agentsecrets/main.go
./agentsecrets --help
```

--------------------------------

### Verify Installation

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Verify the AgentSecrets installation.

```bash
agentsecrets --version
```

--------------------------------

### Install MCP for AI Tools

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Install MCP for Claude Desktop / Cursor / Windsurf.

```bash
agentsecrets mcp install
```

--------------------------------

### Multi-Machine Setup Example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/login.md

Steps to log in and set up AgentSecrets on a second machine.

```bash
agentsecrets login     # decrypts your keys from the server, sets up keychain
agentsecrets status    # verify workspace context
cd your-project/
agentsecrets project use my-backend   # link the directory
agentsecrets secrets pull             # pull secrets to keychain
```

--------------------------------

### Install OpenClaw Skill

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Install the AgentSecrets skill for OpenClaw.

```bash
openclaw skill install agentsecrets
```

--------------------------------

### Examples

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/init.md

Various examples of how to use the agentsecrets init command.

```bash
# Interactive (prompts for all choices)
agentsecrets init

# Keychain mode, skip storage mode prompt (default)
agentsecrets init --storage-mode 1

# Standard .env mode, skip storage mode prompt
agentsecrets init --storage-mode 2

# Force reinitialize without confirmation prompt
agentsecrets init --force

# After running, verify state
agentsecrets status
```

--------------------------------

### Start HTTP Proxy

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Start the AgentSecrets HTTP proxy.

```bash
agentsecrets proxy start
```

--------------------------------

### Go Installation

Source: https://github.com/the-17/agentsecrets/blob/main/npm/README.md

Install AgentSecrets using Go.

```bash
go install github.com/The-17/agentsecrets/cmd/agentsecrets@latest
```

--------------------------------

### Go examples

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Examples of running Go binaries and tests with injected secrets.

```bash
# Run binary
agentsecrets env -- ./myserver

# Run tests that hit real APIs
agentsecrets env -- go test ./pkg/payments/...
```

--------------------------------

### Create a Project

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Create a new project to partition secrets.

```bash
agentsecrets project create my-app
```

--------------------------------

### Start Proxy

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/proxy.md

Starts the HTTP credential proxy on your local machine.

```bash
agentsecrets proxy start [--port 9000]
```

--------------------------------

### Re-running on an Existing Install - Prompt

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/init.md

The prompt shown when re-running init on an existing installation.

```bash
⚠ AgentSecrets is already initialized.
Reinitialize? This will reset your config files.
  Yes
  No
```

--------------------------------

### Incident Response Example

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Demonstrates starting the agentsecrets proxy for incident response, highlighting its secure credential handling.

```bash
agentsecrets proxy start
# Claude queries logs, checks database state, calls APIs
# Full access. Zero credential exposure. Full audit trail.
# You debug. The agent never held your credentials.
```

--------------------------------

### Switch Environment

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Switch the active environment for the current project.

```bash
agentsecrets environment switch staging
```

--------------------------------

### Installation using npm

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Install the AgentSecrets CLI using npm.

```bash
# npm
npm install -g @the-17/agentsecrets
```

--------------------------------

### Installation Methods

Source: https://github.com/the-17/agentsecrets/blob/main/README.md

Provides commands for installing AgentSecrets via Homebrew, npm, pip, and Go.

```bash
# Homebrew (macOS / Linux)
brew install The-17/tap/agentsecrets

# npm
npm install -g @the-17/agentsecrets

# pip
pip install agentsecrets-cli

# Go (recommend using a pinned version for supply chain security)
go install github.com/The-17/agentsecrets/cmd/agentsecrets@v2.0.0
```

--------------------------------

### Initialize AgentSecrets

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Initialize AgentSecrets, prompting for account creation/login and storage mode.

```bash
agentsecrets init
```

--------------------------------

### Homebrew Installation

Source: https://github.com/the-17/agentsecrets/blob/main/docs/ARCHITECTURE.md

Installs keychain-auth via Homebrew.

```bash
brew install The-17/tap/keychain-auth
```

--------------------------------

### Output example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of the output when injecting secrets.

```text
ℹ Injecting 9 secrets: STRIPE_KEY + 8 more
```

--------------------------------

### Quick Start Commands

Source: https://github.com/the-17/agentsecrets/blob/main/npm/README.md

Initialize, create a project, set credentials, authorize domains, and connect AI tools with AgentSecrets.

```bash
# Set up your account (first time) or initialise a new project (returning user)
agentsecrets init

# Create a project
agentsecrets project create my-app

# Store credentials — values go to OS keychain, never to disk
agentsecrets secrets set STRIPE_KEY=sk_live_51H...
agentsecrets secrets set OPENAI_KEY=sk-proj-...
agentsecrets secrets set DATABASE_URL=postgresql://...

# Or push your existing .env all at once
agentsecrets secrets push

# Authorize the domains your agents can reach
agentsecrets workspace allowlist add api.stripe.com api.openai.com

# Connect your AI tool
npx @the-17/agentsecrets mcp install   # Claude Desktop + Cursor
agentsecrets proxy start               # Any agent via HTTP
openclaw skill install agentsecrets    # OpenClaw

# Or inject secrets as env vars into any process
agentsecrets env -- stripe mcp
agentsecrets env -- node server.js
agentsecrets env -- npm run dev
```

--------------------------------

### Installation using pip

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Install the AgentSecrets CLI using pip.

```bash
# pip
pip install agentsecrets-cli
```

--------------------------------

### Import .env File

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Import secrets from an existing .env file.

```bash
agentsecrets secrets push
```

--------------------------------

### Shell / Scripts examples

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Examples of running shell scripts and Docker Compose with injected secrets.

```bash
# A script that sources no .env files — reads from env directly
agentsecrets env -- ./scripts/deploy.sh

# Docker Compose (picks up env vars from the shell)
agentsecrets env -- docker-compose up

# Verify which secrets are visible to the child
agentsecrets env -- printenv | grep STRIPE
agentsecrets env -- printenv DB_URL
```

--------------------------------

### Installation using Homebrew (macOS / Linux)

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Install the full AgentSecrets binary directly using Homebrew.

```bash
# Homebrew (macOS / Linux)
brew install the-17/tap/agentsecrets
```

--------------------------------

### List Stored Secrets

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

List the names of stored secrets.

```bash
agentsecrets secrets list
```

--------------------------------

### Installation Options

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/SKILL.md

Various methods to install the agentsecrets CLI binary.

```bash
- npx @the-17/agentsecrets (Run without install)
- brew install The-17/tap/agentsecrets (macOS/Linux)
- pip install agentsecrets-cli (Python/Universal)
- go install github.com/The-17/agentsecrets/cmd/agentsecrets@v2.0.0 (Go devs - prefer pinned version)
```

--------------------------------

### Quick Start: Initialize a new project and store credentials

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Steps to initialize AgentSecrets, create a project, and securely store credentials using the CLI.

```bash
# Set up your account (first time) or initialise a new project (returning user)
agentsecrets init

# Create a project
agentsecrets project create my-app

# Store credentials — values go to OS keychain, never to disk
agentsecrets secrets set STRIPE_KEY=sk_live_51H...
agentsecrets secrets set OPENAI_KEY=sk-proj-...
agentsecrets secrets set DATABASE_URL=postgresql://...

# Or push your existing .env all at once
agentsecrets secrets push

# Authorize the domains your agents can reach
agentsecrets workspace allowlist add api.stripe.com api.openai.com
```

--------------------------------

### list_secrets Tool Example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/PROXY.md

Example prompt for discovering available secret keys using the list_secrets tool.

```text
> "What API keys do I have in this project?"

Found 3 secret(s):

  • STRIPE_KEY
  • OPENAI_API_KEY
  • GITHUB_TOKEN

Use these key names in api_call's injections parameter.
```

--------------------------------

### npm/npx Installation

Source: https://github.com/the-17/agentsecrets/blob/main/npm/README.md

Install AgentSecrets globally using npm or use npx to run without installation.

```bash
npm install -g @the-17/agentsecrets
# or without installing
npx @the-17/agentsecrets init
```

--------------------------------

### Authorize API Domains

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Add API domains to the workspace allowlist.

```bash
agentsecrets workspace allowlist add api.stripe.com api.openai.com
```

--------------------------------

### Solo Developer Use Case

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example workflow for a solo developer initializing AgentSecrets, setting a secret, installing MCP, and having an AI agent manage calls.

```bash
agentsecrets init
agentsecrets secrets set STRIPE_KEY=sk_live_...
agentsecrets mcp install
# Ask Claude to check your Stripe balance. It manages the call. Never sees the key.
```

--------------------------------

### Start HTTP Proxy Server

Source: https://github.com/the-17/agentsecrets/blob/main/docs/PROXY.md

Commands to start the HTTP proxy server on the default or a custom port.

```bash
agentsecrets proxy start              # Default port 8765
agentsecrets proxy start --port 9000  # Custom port
```

--------------------------------

### Quick Start: Connect your AI tool

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Instructions for connecting various AI tools and agents to AgentSecrets.

```bash
# Connect your AI tool
agentsecrets mcp install               # Claude Desktop + Cursor
agentsecrets proxy start               # Any agent via HTTP
openclaw skill install agentsecrets    # OpenClaw
```

--------------------------------

### Initialize AgentSecrets (non-interactive)

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Initialize AgentSecrets without interactive prompts, specifying storage mode.

```bash
agentsecrets init --storage-mode 1   # Keychain mode (default)
```

```bash
agentsecrets init --storage-mode 2   # Standard .env mode
```

--------------------------------

### Django project example (full Makefile)

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

A complete Makefile example for a Django project using agentsecrets env.

```makefile
RUN := agentsecrets env --

.PHONY: dev test migrate shell celery

dev:
	$(RUN) python manage.py runserver

test:
	$(RUN) python manage.py test

migrate:
	$(RUN) python manage.py migrate

shell:
	$(RUN) python manage.py shell

celery:
	$(RUN) celery -A myapp worker --loglevel=info

# Run without injection (for debugging env setup)
dev-raw:
	python manage.py runserver
```

--------------------------------

### Exit Codes example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example demonstrating how agentsecrets env passes through child exit codes.

```bash
agentsecrets env -- python manage.py test
echo $?  # exit code from Django test runner, not from agentsecrets
```

--------------------------------

### api_call Tool Example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/PROXY.md

Example prompt for making an authenticated API call using the api_call tool, demonstrating secret injection.

```json
{
  "url": "https://api.stripe.com/v1/charges",
  "method": "POST",
  "body": "{\"amount\": 1000, \"currency\": \"usd\", \"source\": \"tok_visa\"}",
  "injections": {"bearer": "STRIPE_KEY"}
}
```

--------------------------------

### Node.js example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of reading secrets from process.env in a Node.js application.

```javascript
// server.js — reads from process.env as normal
const stripe = require('stripe')(process.env.STRIPE_KEY);  // injected
const db = require('./db')(process.env.DATABASE_URL);       // injected
```

--------------------------------

### AgentSecrets CLI Examples

Source: https://github.com/the-17/agentsecrets/blob/main/README.md

Examples of using the agentsecrets CLI for various operations like API calls with different authentication methods and query parameters.

```bash
agentsecrets call --url https://api.sendgrid.com/v3/mail/send \
  --header X-Api-Key=SENDGRID_KEY
```

```bash
agentsecrets call \
  --url "https://maps.googleapis.com/maps/api/geocode/json?address=Lagos" \
  --query key=GOOGLE_MAPS_KEY
```

```bash
agentsecrets call --url https://jira.example.com/rest/api/2/issue \
  --basic JIRA_CREDS
```

```bash
agentsecrets call --url https://api.example.com/auth \
  --body-field client_secret=SECRET
```

```bash
agentsecrets call --url https://oauth.example.com/token \
  --form-field api_key=KEY
```

--------------------------------

### Re-running on an Existing Install - Force

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/init.md

Command to force reinitialize non-interactively.

```bash
agentsecrets init --force
```

--------------------------------

### Switching Environments

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/environment.md

Example of switching to the staging environment and pulling secrets.

```bash
agentsecrets environment switch staging
# Successfully switched to staging environment.

agentsecrets secrets pull
# Synced 12 secrets from cloud to OS keychain.
# This is environment scoped
```

--------------------------------

### Proxy Request Example

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example cURL request to the AgentSecrets HTTP proxy.

```bash
curl http://localhost:8765/proxy \
  -H "X-AS-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-AS-Inject-Bearer: STRIPE_KEY"
```

--------------------------------

### Typical onboarding flow

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/project.md

Example of a typical onboarding flow for a new team member using agentsecrets project use.

```bash
git clone https://github.com/yourcompany/backend
cd backend
agentsecrets project use prod-backend
agentsecrets secrets pull
```

--------------------------------

### Store Secrets

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Store individual secrets.

```bash
agentsecrets secrets set STRIPE_KEY=sk_live_51H...
```

```bash
agentsecrets secrets set DATABASE_URL=postgresql://user:pass@host/db
```

```bash
agentsecrets secrets set OPENAI_KEY=sk-proj-...
```

--------------------------------

### Demo B: Start the proxy and verify health

Source: https://github.com/the-17/agentsecrets/blob/main/docs/DEMO_SCRIPT.md

Commands to start the AgentSecrets HTTP proxy and check its health status.

```bash
# Terminal 1: Start the proxy
agentsecrets proxy start

# Terminal 2: Verify health
curl http://localhost:8765/health
```

--------------------------------

### Single secret output example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of the output when injecting a single secret.

```text
ℹ Injecting 1 secret: STRIPE_KEY
```

--------------------------------

### Environment Variable Injection Examples

Source: https://github.com/the-17/agentsecrets/blob/main/README.md

Examples of using agentsecrets to inject environment variables into child processes for various tools and scripts.

```bash
agentsecrets env -- stripe mcp
```

```bash
agentsecrets env -- node server.js
```

```bash
agentsecrets env -- python manage.py runserver
```

```bash
agentsecrets env -- npm run dev
```

--------------------------------

### When to Use - Switching Accounts

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/logout.md

Example of logging out to switch to a different account.

```bash
agentsecrets logout
agentsecrets login   # or agentsecrets init for a new account
```

--------------------------------

### Building and Running Agent Secrets

Source: https://github.com/the-17/agentsecrets/blob/main/AGENT.md

Instructions for cloning the repository, installing dependencies, building the project, running tests, and running the application locally.

```bash
# Clone
git clone https://github.com/The-17/agentsecrets
cd agentsecrets

# Install dependencies
go mod download

# Build
make build
# or
go build -o agentsecrets ./cmd/agentsecrets

# Run tests
make test
# or
go test ./...

# Run locally
go run ./cmd/agentsecrets/main.go
```

--------------------------------

### Django settings.py example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of a Django settings.py file reading environment variables, including those injected by agentsecrets env.

```python
# settings.py — reads from env as normal
import os

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ["DB_NAME"],
        "USER": os.environ["DB_USER"],
        "PASSWORD": os.environ["DB_PASSWORD"],  # injected by agentsecrets env
        "HOST": os.environ["DB_HOST"],
        "PORT": os.environ.get("DB_PORT", "5432"),
    }
}

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]   # injected by agentsecrets env
STRIPE_SECRET_KEY = os.environ["STRIPE_KEY"]   # injected by agentsecrets env
```

--------------------------------

### Check Audit Log

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

View the AgentSecrets proxy audit log.

```bash
agentsecrets proxy logs --last 5
```

--------------------------------

### Make Authenticated API Call

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Make a one-shot authenticated API call using a secret key name.

```bash
agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
```

--------------------------------

### Team Workspace Setup

Source: https://github.com/the-17/agentsecrets/blob/main/README.md

Commands for creating team workspaces, inviting members, creating projects, and onboarding new developers.

```bash
agentsecrets workspace create "The Seventeen Engineering"
agentsecrets workspace invite alice@theseventeen.co bob@theseventeen.co

agentsecrets project create payments-service
agentsecrets project create auth-service
```

```bash
# New developer onboards:
agentsecrets login
agentsecrets workspace switch "The Seventeen Engineering"
agentsecrets project use payments-service
agentsecrets secrets pull
# Ready. No credential sharing. No .env files sent over Slack.
```

--------------------------------

### Audit Log Format Example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/PROXY.md

Example of the JSONL format for entries in the proxy audit log.

```json
{
  "timestamp": "2026-02-25T10:00:00Z",
  "secret_keys": ["STRIPE_KEY"],
  "agent_id": "mcp",
  "method": "POST",
  "target_url": "https://api.stripe.com/v1/charges",
  "auth_styles": ["bearer"],
  "status_code": 200,
  "status": "OK",
  "reason": "-",
  "redacted": false,
  "duration_ms": 245
}
```

--------------------------------

### POST with body

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/call.md

Example of making a POST request with a JSON body.

```bash
agentsecrets call \
  --url https://api.stripe.com/v1/charges \
  --method POST \
  --bearer STRIPE_KEY \
  --body '{"amount": 1000, "currency": "usd", "source": "tok_visa"}'
```

--------------------------------

### Install AgentSecrets CLI using Homebrew

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/README.md

Installs the AgentSecrets CLI using Homebrew.

```bash
brew install The-17/tap/agentsecrets
```

--------------------------------

### Proxy and Calls

Source: https://github.com/the-17/agentsecrets/blob/main/AGENT.md

Examples of using agentsecrets for making direct calls and managing the proxy.

```bash
agentsecrets call --url URL --bearer KEY
agentsecrets call --url URL --method POST --bearer KEY --body '{}'
agentsecrets call --url URL --header Name=KEY
agentsecrets call --url URL --query param=KEY
agentsecrets call --url URL --basic KEY
agentsecrets call --url URL --body-field path=KEY
agentsecrets call --url URL --form-field field=KEY
agentsecrets proxy start [--port 8765]
agentsecrets proxy status
agentsecrets proxy sync
agentsecrets proxy stop
agentsecrets proxy logs [--last N] [--watch] [--secret KEY]
agentsecrets exec
agentsecrets mcp serve
agentsecrets mcp install
```

--------------------------------

### Prerequisites: AgentSecrets installation and configuration

Source: https://github.com/the-17/agentsecrets/blob/main/docs/DEMO_SCRIPT.md

Commands to log in to AgentSecrets, select a project, and set a secret.

```bash
agentsecrets login
agentsecrets project use demo-project
```

```bash
agentsecrets secrets set STRIPE_KEY=sk_test_your_stripe_test_key_here
```

```bash
agentsecrets secrets list
# Should show: STRIPE_KEY
```

--------------------------------

### Basic auth

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/call.md

Example of using basic authentication with credentials stored in the keychain.

```bash
# JIRA_CREDS stored in keychain as "user@email.com:api_token"
agentsecrets call \
  --url https://yourcompany.atlassian.net/rest/api/2/issue/PROJ-123 \
  --basic JIRA_CREDS
```

--------------------------------

### Auth Styles - Query Parameter

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example of making an API call using a query parameter.

```bash
# Query parameter (Google Maps, weather APIs)
agentsecrets call --url "https://maps.googleapis.com/maps/api/geocode/json" \
  --query key=GMAP_KEY
```

--------------------------------

### Monorepo Directory Structure

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/project.md

Example of how to structure directories for monorepos with AgentSecrets.

```directory
repo/
├── .agent/
│   └── workflows/
│       └── agentsecrets.md    # Shared agent instructions
├── services/
│   ├── api/
│   │   └── .agentsecrets/
│   │       └── project.json    # project: api-service
│   └── worker/
│       └── .agentsecrets/
│           └── project.json    # project: worker-service
└── ...
```

--------------------------------

### Environment Variable Injection

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Examples of wrapping commands to inject secrets as environment variables.

```bash
# Wrap any command — secrets injected as env vars
agentsecrets env -- python manage.py runserver
agentsecrets env -- celery -A myapp worker
agentsecrets env -- pytest
```

--------------------------------

### Multiple credentials

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/call.md

Example of using multiple credentials in a single call.

```bash
agentsecrets call \
  --url https://api.example.com/data \
  --bearer AUTH_TOKEN \
  --header X-Org-Id=ORG_SECRET
```

--------------------------------

### Inject Environment Variables for CLI Tools

Source: https://github.com/the-17/agentsecrets/blob/main/docs/QUICKSTART.md

Inject secrets as environment variables for CLI tools.

```bash
agentsecrets env -- stripe mcp
```

```bash
agentsecrets env -- node server.js
```

```bash
agentsecrets env -- python manage.py runserver
```

--------------------------------

### Quick Start: Inject secrets as environment variables into Python processes

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Demonstrates how to inject secrets as environment variables into Python processes using AgentSecrets.

```bash
# Or inject secrets as env vars into any Python process
agentsecrets env -- python manage.py runserver
agentsecrets env -- celery -A myapp worker
agentsecrets env -- pytest
```

--------------------------------

### Proxy and Calls Commands

Source: https://github.com/the-17/agentsecrets/blob/main/README.md

Commands for making calls, starting, stopping, and managing the proxy server, and serving MCP.

```bash
agentsecrets call --url URL --bearer KEY
agentsecrets proxy start [--port 8765]
agentsecrets proxy status
agentsecrets proxy stop
agentsecrets proxy logs [--last N] [--watch] [--env ENV]
agentsecrets mcp serve
agentsecrets mcp install
agentsecrets exec
agentsecrets env -- <command>
```

--------------------------------

### Auth Styles - Custom Header

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example of making an API call using a custom header.

```bash
# Custom header (SendGrid, Twilio, API Gateway)
agentsecrets call --url https://api.sendgrid.com/v3/mail/send \
  --header X-Api-Key=SENDGRID_KEY
```

--------------------------------

### Python / Django - Run migrations

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of running Django migrations with secrets injected.

```bash
agentsecrets env -- python manage.py migrate
```

--------------------------------

### Node.js / Express - Next.js

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of running a Next.js development server with secrets injected.

```bash
agentsecrets env -- npx next dev
```

--------------------------------

### Copying Secrets Between Environments

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/environment.md

Example of copying all secrets from the development environment to the staging environment.

```bash
agentsecrets environment copy development staging
# Copied 12 secrets from development to staging.
```

--------------------------------

### Python / Django - Run Django development server

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of running the Django development server with secrets injected.

```bash
agentsecrets env -- python manage.py runserver
```

--------------------------------

### Runtime retrieval (the common pattern)

Source: https://github.com/the-17/agentsecrets/blob/main/README.md

An example of the common pattern where an agent retrieves a credential at runtime, leading to potential exposure.

```bash
export TOKEN=$(secrets lease github_token)
# The agent now holds sk_live_51H... in memory
```

--------------------------------

### Common Secret Naming Conventions

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/secrets.md

Examples of common patterns for secret key naming conventions.

```bash
# API keys
STRIPE_KEY
OPENAI_KEY
GITHUB_TOKEN
SENDGRID_KEY

# Database
DATABASE_URL
REDIS_URL

# Application
DJANGO_SECRET_KEY
JWT_SECRET
SESSION_SECRET

# Service accounts
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
GCP_SERVICE_ACCOUNT_JSON
```

--------------------------------

### Making Authenticated API Calls

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/SKILL.md

Examples of using the `call` proxy for secure API requests with different authentication methods.

```bash
agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
agentsecrets call --url https://api.example.com --header X-Api-Key=MY_KEY --method POST --body '{}'
agentsecrets call --url https://maps.example.com --query key=MAPS_KEY
agentsecrets call --url https://jira.example.com --basic JIRA_CREDS
```

--------------------------------

### Custom header (API key in header)

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/call.md

Example of sending an API key in a custom header.

```bash
agentsecrets call \
  --url https://api.sendgrid.com/v3/mail/send \
  --method POST \
  --header X-Api-Key=SENDGRID_KEY \
  --body '{"personalizations":[...]}'
```

--------------------------------

### Audit Log example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of an entry in the agentsecrets proxy log.

```json
{
  "timestamp": "2026-03-03T22:00:00Z",
  "method": "ENV",
  "target_url": "python manage.py runserver",
  "secret_keys": ["DB_PASSWORD", "STRIPE_KEY", "DJANGO_SECRET_KEY"],
  "auth_styles": ["env_inject"],
  "status": "OK",
  "reason": "-"
}
```

--------------------------------

### Usage

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/init.md

The basic command to initialize AgentSecrets.

```bash
agentsecrets init [--storage-mode 0|1]
```

--------------------------------

### Manually install AgentSecrets

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/README.md

Manually copies the AgentSecrets integration files to the OpenClaw skills directory.

```bash
cp -r integrations/openclaw ~/.openclaw/skills/agentsecrets
```

--------------------------------

### Autonomous Agent Deployment Use Case

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example workflow for autonomous agent deployment, including secret diffing, pulling, environment switching, and deployment execution.

```bash
# Agent handles this entire flow without human intervention
agentsecrets secrets diff                    # checks for drift
agentsecrets secrets pull                    # syncs if needed
agentsecrets environment switch production   # switch to production environment
agentsecrets secrets pull                    # pull production secrets
agentsecrets env -- python deploy.py
agentsecrets proxy logs                      # audits what happened
```

--------------------------------

### Project Config File

Source: https://github.com/the-17/agentsecrets/blob/main/docs/ARCHITECTURE.md

Example of the project-specific configuration file located at .agentsecrets/project.json, linking the directory to a remote project.

```JSON
{
  "project_id": "proj_xyz789",
  "project_name": "my-app",
  "workspace_id": "ws_abc123",
  "storage_mode": 1,
  "last_pull": "2026-03-03T22:00:00Z",
  "last_push": "2026-03-03T21:00:00Z"
}
```

--------------------------------

### Python / Django - Django shell with secrets available

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of running a Django shell with secrets injected.

```bash
agentsecrets env -- python manage.py shell
```

--------------------------------

### Storage Mode Selection

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/init.md

Commands to select between Keychain and standard .env file storage modes.

```bash
agentsecrets init --storage-mode 1   # Keychain (recommended)
```

```bash
agentsecrets init --storage-mode 0   # Standard .env
```

--------------------------------

### AgentSecrets Python SDK Installation

Source: https://github.com/the-17/agentsecrets/blob/main/README.md

Command to install the agentsecrets Python SDK using pip.

```python
pip install agentsecrets
```

--------------------------------

### Files Written - Project-local

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/init.md

Project-local files written by AgentSecrets init.

```bash
.agentsecrets/
  project.json         # project_id, workspace_id, storage_mode, last sync timestamps
.agent/
  workflows/
    agentsecrets.md    # AI assistant workflow file (teaches the agent how to use AgentSecrets)
```

--------------------------------

### Basic auth (Jira, legacy REST APIs)

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example of using AgentSecrets for basic authentication with Jira or legacy REST APIs.

```bash
agentsecrets call --url https://jira.example.com/rest/api/2/issue \
  --basic JIRA_CREDS
```

--------------------------------

### HTTP Proxy Query Parameter Injection

Source: https://github.com/the-17/agentsecrets/blob/main/docs/PROXY.md

Example using curl to make a request to the HTTP proxy with query parameter injection.

```bash
curl http://localhost:8765/proxy \
  -H "X-AS-Target-URL: https://maps.googleapis.com/maps/api/geocode/json?address=NYC" \
  -H "X-AS-Inject-Query-key: GOOGLE_MAPS_KEY"
```

--------------------------------

### Demo A: Build the binary

Source: https://github.com/the-17/agentsecrets/blob/main/docs/DEMO_SCRIPT.md

Command to build the AgentSecrets binary.

```bash
cd /home/theapiartist/work/agentsecrets
go build -o agentsecrets ./cmd/agentsecrets
```

--------------------------------

### Install AgentSecrets CLI using pip

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/README.md

Installs the AgentSecrets CLI using pip.

```bash
pip install agentsecrets-cli
```

--------------------------------

### Install AgentSecrets CLI using npm

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/README.md

Installs the AgentSecrets CLI using npm.

```bash
npm install -g @the-17/agentsecrets
```

--------------------------------

### Files Written - Global

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/init.md

Global files written by AgentSecrets init.

```bash
~/.agentsecrets/
  config.json          # workspace keys, active context, JWT token
  proxy.log            # audit log (appended by proxy/call/env)
```

--------------------------------

### New developer onboarding

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Workflow for a new developer to onboard and access necessary secrets.

```bash
agentsecrets login
agentsecrets workspace switch "Acme Engineering"
agentsecrets project use payments-service
agentsecrets secrets pull
# Ready. No credential sharing. No .env files sent over Slack.
```

--------------------------------

### Response Body Redaction Example

Source: https://github.com/the-17/agentsecrets/blob/main/docs/ARCHITECTURE.md

Example showing how Agent Secrets redacts echoed authentication headers in API response bodies and updates the audit log.

```text
Response from api.example.com:
{"authenticated": true, "token": "sk_live_51H..."}
                                   ↑ matched as echoed credential

After redaction:
{"authenticated": true, "token": "[REDACTED_BY_AGENTSECRETS]"}

Audit log:
{"reason": "credential_echo", "redacted": true}
```

--------------------------------

### Agent Workflow Example

Source: https://github.com/the-17/agentsecrets/blob/main/README.md

Illustrates a typical workflow for an AI agent using AgentSecrets, including checking status, synchronizing secrets, making API calls, and viewing proxy logs.

```bash
agentsecrets status
# Workspace:    Acme Engineering
# Project:      payments-service
# Environment:  production
# Last pull:    2 minutes ago

agentsecrets secrets diff
# OUT OF SYNC: STRIPE_KEY (remote is newer)

agentsecrets secrets pull
# Synced 1 secret from cloud to OS keychain

agentsecrets call \
  --url https://api.stripe.com/v1/balance \
  --bearer STRIPE_KEY
# {"object":"balance","available":[{"amount":420000,"currency":"usd"}]}

agentsecrets proxy logs --last 5
# 14:23:01  GET  api.stripe.com/v1/balance  STRIPE_KEY  200  245ms
```

--------------------------------

### Form field injection

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example of injecting form fields into an API call.

```bash
agentsecrets call --url https://oauth.example.com/token \
  --form-field api_key=KEY
```

--------------------------------

### JSON body injection

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example of injecting a JSON body into an API call.

```bash
agentsecrets call --url https://api.example.com/auth \
  --body-field client_secret=SECRET
```

--------------------------------

### Form-encoded body

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/call.md

Example of sending a form-encoded body with injected secrets.

```bash
agentsecrets call \
  --url https://oauth.example.com/token \
  --method POST \
  --form-field api_key=API_KEY \
  --form-field client_id=CLIENT_ID
```

--------------------------------

### Query parameter

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/call.md

Example of injecting a secret as a URL query parameter.

```bash
agentsecrets call \
  --url "https://maps.googleapis.com/maps/api/geocode/json?address=Lagos" \
  --query key=GOOGLE_MAPS_KEY
```

--------------------------------

### When to Use - Security Incident

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/logout.md

Example of logging out after a credential-related security incident.

```bash
agentsecrets logout
# Then rotate the affected secrets:
agentsecrets secrets set COMPROMISED_KEY=new_value
```

--------------------------------

### Create project

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/project.md

Creates a new project in the active workspace and links the current directory to it.

```bash
agentsecrets project create my-backend
```

--------------------------------

### Build AgentSecrets

Source: https://github.com/the-17/agentsecrets/blob/main/docs/PROXY.md

Build the AgentSecrets executable.

```bash
go build -o agentsecrets ./cmd/agentsecrets
```

--------------------------------

### Agentsecrets project use

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Command to set the active project.

```bash
agentsecrets project use my-app
```

--------------------------------

### Testing

Source: https://github.com/the-17/agentsecrets/blob/main/docs/CONTRIBUTING.md

Commands for running tests, including options for coverage and verbosity, and how to test specific packages.

```bash
# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests verbosely
go test -v ./...

# Test specific package
go test ./pkg/crypto/...
go test ./pkg/proxy/...
go test ./pkg/auth/...
```

--------------------------------

### Proxy and Calls Commands

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Commands for making authenticated calls, starting/managing the HTTP proxy, and viewing logs.

```bash
agentsecrets call --url <URL> --bearer KEY    # One-shot authenticated call
agentsecrets proxy start [--port 8765]        # Start HTTP proxy
agentsecrets proxy status                     # Check proxy status & revocation list
agentsecrets proxy sync                       # Force background revocation sync
agentsecrets proxy logs [--last N] [--watch]  # View or stream local audit trail
agentsecrets exec                             # OpenClaw exec provider (reads stdin)
agentsecrets mcp serve                        # Start MCP server
agentsecrets mcp install                      # Auto-configure AI tools
```

--------------------------------

### List projects

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/project.md

Lists all projects in the active workspace.

```bash
agentsecrets project list
```

--------------------------------

### Auth Styles - Bearer Token

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example of making an API call using a bearer token.

```bash
# Bearer token (Stripe, OpenAI, GitHub, most modern APIs)
agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
```

--------------------------------

### CLI Command Surface - Workspace Allowlist

Source: https://github.com/the-17/agentsecrets/blob/main/AGENT.md

Commands for managing the workspace allowlist.

```bash
agentsecrets workspace allowlist add <domain> [domain...]  # Authorize domains
agentsecrets workspace allowlist list                      # List allowed domains
agentsecrets workspace allowlist log                       # View allowlist audit log
```

--------------------------------

### Make authenticated calls

Source: https://github.com/the-17/agentsecrets/blob/main/pypi/README.md

Example of making an authenticated API call using a bearer token.

```bash
agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
# {"object":"balance","available":[{"amount":420000,"currency":"usd"}]}
```

--------------------------------

### Environment Injection

Source: https://github.com/the-17/agentsecrets/blob/main/AGENT.md

Examples of using agentsecrets to inject secrets as environment variables into child processes.

```bash
agentsecrets env -- <command> [args...]  # Inject secrets as env vars into child process
agentsecrets env -- stripe mcp           # Wrap Stripe MCP
agentsecrets env -- node server.js       # Wrap Node.js
```

--------------------------------

### Stripe CLI commands

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Examples of using agentsecrets env with Stripe CLI commands.

```bash
# Start Stripe MCP server
agentsecrets env -- stripe mcp

# Forward webhook events to local server
agentsecrets env -- stripe listen --forward-to localhost:3000/webhooks

# Trigger a test event
agentsecrets env -- stripe trigger payment_intent.created
```

--------------------------------

### Download Full Documentation

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/SKILL.md

Curl command to download the complete AgentSecrets documentation as a single Markdown file.

```bash
curl -s "https://agentsecrets.theseventeen.co/llms-full.txt"
```

--------------------------------

### Python / Django - Celery worker

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/env.md

Example of running a Celery worker with secrets injected.

```bash
agentsecrets env -- celery -A myapp worker --loglevel=info
```

--------------------------------

### Troubleshooting & Docs

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/SKILL.md

Commands for viewing logs, authorizing domain allowlist changes, and accessing help.

```bash
agentsecrets proxy logs --last 10
agentsecrets workspace allowlist add <domain>
agentsecrets --help
```

--------------------------------

### workspace create command

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/workspace.md

Creates a new shared workspace and immediately switches to it. Any projects created after this point belong to the new workspace.

```bash
agentsecrets workspace create "Acme Backend Team"
```

--------------------------------

### JSON body injection

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/call.md

Example of injecting a secret into a JSON body at a specific path.

```bash
# Inject secret into JSON body at a specific path
agentsecrets call \
  --url https://api.example.com/oauth/token \
  --method POST \
  --body '{"grant_type": "client_credentials"}' \
  --body-field client_secret=CLIENT_SECRET
```

--------------------------------

### Conventional Commits Format

Source: https://github.com/the-17/agentsecrets/blob/main/docs/CONTRIBUTING.md

Examples of commit messages following the conventional commits format.

```text
feat: add secrets rotation command
fix: handle network errors gracefully
docs: update installation instructions
test: add crypto package tests
refactor: simplify workspace switching logic
chore: update dependencies
```

--------------------------------

### Environments & Workspaces

Source: https://github.com/the-17/agentsecrets/blob/main/integrations/openclaw/SKILL.md

Commands for switching environments and managing projects.

```bash
agentsecrets environment switch production # (Ask for confirmation first)
agentsecrets project create OPENCLAW_MANAGER
agentsecrets project use OPENCLAW_MANAGER
```

--------------------------------

### Bearer token (most common)

Source: https://github.com/the-17/agentsecrets/blob/main/docs/commands/call.md

Example of using agentsecrets call with a bearer token for authentication.

```bash
agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
agentsecrets call --url https://api.openai.com/v1/models --bearer OPENAI_KEY
```