secrets

thepopebot provides three commands for managing GitHub repository secrets and variables: set-agent-secret, set-agent-llm-secret, and set-var. These commands use the GitHub CLI (gh) to update secrets and variables in your repository. They read GH_OWNER and GH_REPO from your .env file.

Secret Prefix Convention

GitHub secrets use a prefix convention to control how they’re passed to the Docker agent:

AGENT_ — Protected secrets passed to the Docker container but filtered from the LLM. The agent can use these in API calls, but they’re redacted from prompts and responses.
- Examples: AGENT_GH_TOKEN, AGENT_ANTHROPIC_API_KEY, AGENT_OPENAI_API_KEY
AGENT_LLM_ — LLM-accessible secrets not filtered. The agent can see and use these values in prompts.
- Examples: AGENT_LLM_BRAVE_API_KEY, AGENT_LLM_CUSTOM_TOKEN
No prefix — Workflow-only secrets, never passed to the container.
- Examples: GH_WEBHOOK_SECRET

The set-agent-secret and set-agent-llm-secret commands automatically add the appropriate prefix.

set-agent-secret

Set a GitHub secret with the AGENT_ prefix and update your local .env file.

Usage

npx thepopebot set-agent-secret ANTHROPIC_API_KEY

Parameters

KEY (required) — Secret name without the AGENT_ prefix
VALUE (optional) — Secret value. If omitted, you’ll be prompted with masked input

Behavior

Prompts for value if not provided (masked input, not saved to shell history)
Sets GitHub secret: AGENT_<KEY>
Updates .env: <KEY>=<value> (without prefix)

Example

npx thepopebot set-agent-secret ANTHROPIC_API_KEY

? Enter value for ANTHROPIC_API_KEY: ••••••••••••••••

  Set GitHub secret: AGENT_ANTHROPIC_API_KEY
  Updated .env: ANTHROPIC_API_KEY

This creates:

GitHub secret: AGENT_ANTHROPIC_API_KEY=sk-ant-abc123
.env entry: ANTHROPIC_API_KEY=sk-ant-abc123

The Docker agent reads AGENT_ANTHROPIC_API_KEY from the GitHub Actions environment, but the event handler reads ANTHROPIC_API_KEY from .env.

set-agent-llm-secret

Set a GitHub secret with the AGENT_LLM_ prefix. This secret is not filtered — the LLM can see it.

Usage

npx thepopebot set-agent-llm-secret BRAVE_API_KEY

Parameters

KEY (required) — Secret name without the AGENT_LLM_ prefix
VALUE (optional) — Secret value. If omitted, you’ll be prompted with masked input

Behavior

Prompts for value if not provided (masked input)
Sets GitHub secret: AGENT_LLM_<KEY>
Does not update .env (LLM-accessible secrets are only for agent jobs, not the event handler)

Example

npx thepopebot set-agent-llm-secret BRAVE_API_KEY

? Enter value for BRAVE_API_KEY: ••••••••••••••••

  Set GitHub secret: AGENT_LLM_BRAVE_API_KEY

This creates:

GitHub secret: AGENT_LLM_BRAVE_API_KEY=BSAabc123xyz
.env: unchanged

The Docker agent can see this value in prompts and use it in web search or other LLM-driven tasks.

set-var

Set a GitHub repository variable (not a secret). Variables are visible in the GitHub UI and in workflow logs.

Usage

npx thepopebot set-var APP_URL

Parameters

KEY (required) — Variable name
VALUE (optional) — Variable value. If omitted, you’ll be prompted with masked input

Behavior

Prompts for value if not provided (masked input)
Sets GitHub repository variable: <KEY>
Does not update .env (use set-agent-secret if you need both)

Example

npx thepopebot set-var APP_URL https://new-url.ngrok.io

  Set GitHub variable: APP_URL

This updates the APP_URL GitHub variable to https://new-url.ngrok.io.

Common Variables

Variable	Description
`APP_URL`	Public HTTPS URL for webhooks
`LLM_PROVIDER`	Agent LLM provider (`anthropic`, `openai`, `google`, `custom`)
`LLM_MODEL`	Agent LLM model (e.g., `claude-sonnet-4-20250514`)
`GH_OWNER`	Repository owner
`GH_REPO`	Repository name
`RUNS_ON`	GitHub Actions runner type (`ubuntu-latest` or `self-hosted`)

Masked Input

When you omit the VALUE argument, all three commands prompt for input with masked display:

npx thepopebot set-agent-secret ANTHROPIC_API_KEY

? Enter value for ANTHROPIC_API_KEY: ••••••••••••••••

This keeps secrets out of your shell history.

Piped Input

You can pipe values to avoid interactive prompts:

echo "sk-ant-abc123" | npx thepopebot set-agent-secret ANTHROPIC_API_KEY

cat secret.txt | npx thepopebot set-agent-llm-secret BRAVE_API_KEY

When to Use Each Command

Use `set-agent-secret` When:

The secret is for API authentication (Anthropic, OpenAI, GitHub PAT)
You want the secret in both GitHub (for agent jobs) and .env (for event handler)
The secret should be filtered from LLM prompts

Use `set-agent-llm-secret` When:

The secret is safe for the LLM to see (e.g., Brave Search API key)
The secret is only needed in agent jobs (not the event handler)
You want the agent to use the secret in web searches or LLM-driven tasks

Use `set-var` When:

The value is not sensitive (URLs, model names, flags)
You only need to update the GitHub variable (not .env)
The value is visible in workflow logs (variables are not encrypted)

Example: Update ngrok URL

When your ngrok URL changes, update APP_URL everywhere:

npx thepopebot set-var APP_URL https://new-url.ngrok.io

This updates the GitHub variable. If you also use Telegram, re-register the webhook:

npm run setup-telegram

Example: Add a New API Key

Add an OpenAI key for voice transcription:

npx thepopebot set-agent-secret OPENAI_API_KEY

? Enter value for OPENAI_API_KEY: ••••••••••••••••

  Set GitHub secret: AGENT_OPENAI_API_KEY
  Updated .env: OPENAI_API_KEY

Now:

Event handler (chat, Telegram) can use it via process.env.OPENAI_API_KEY
Agent jobs (Docker containers) can use it via process.env.AGENT_OPENAI_API_KEY
The value is filtered from LLM prompts

Example: Switch to a Different Model

Change the agent LLM model to Claude Opus:

npx thepopebot set-var LLM_MODEL claude-opus-4-20250514

This updates the GitHub variable. New agent jobs will use Opus. Note: This only affects agent jobs. To change the chat LLM, update .env directly:

echo "LLM_MODEL=claude-opus-4-20250514" >> .env

Or re-run setup:

npm run setup

Viewing Secrets and Variables

GitHub secrets are encrypted and not visible in the UI. To view variables:

Go to your repository on GitHub
Settings > Secrets and variables > Actions
Click the Variables tab

Or use the GitHub CLI:

gh variable list

Deleting Secrets and Variables

Use the GitHub CLI or UI:

gh secret delete AGENT_ANTHROPIC_API_KEY
gh variable delete APP_URL

Or in the GitHub UI:

Settings > Secrets and variables > Actions
Find the secret/variable and click Delete

Commands

Secret Prefix Convention

set-agent-secret

Usage

Parameters

Behavior

Example

set-agent-llm-secret

Usage

Parameters

Behavior

Example

set-var

Usage

Parameters

Behavior

Example

Common Variables

Masked Input

Piped Input

When to Use Each Command

Use `set-agent-secret` When:

Use `set-agent-llm-secret` When:

Use `set-var` When:

Example: Update ngrok URL

Example: Add a New API Key

Example: Switch to a Different Model

Viewing Secrets and Variables

Deleting Secrets and Variables

Build docs developers (and LLMs) love

Commands

​Secret Prefix Convention

​set-agent-secret

​Usage

​Parameters

​Behavior

​Example

​set-agent-llm-secret

​Usage

​Parameters

​Behavior

​Example

​set-var

​Usage

​Parameters

​Behavior

​Example

​Common Variables

​Masked Input

​Piped Input

​When to Use Each Command

​Use set-agent-secret When:

​Use set-agent-llm-secret When:

​Use set-var When:

​Example: Update ngrok URL

​Example: Add a New API Key

​Example: Switch to a Different Model

​Viewing Secrets and Variables

​Deleting Secrets and Variables

Build docs developers (and LLMs) love

Secret Prefix Convention

set-agent-secret

Usage

Parameters

Behavior

Example

set-agent-llm-secret

Usage

Parameters

Behavior

Example

set-var

Usage

Parameters

Behavior

Example

Common Variables

Masked Input

Piped Input

When to Use Each Command

Use `set-agent-secret` When:

Use `set-agent-llm-secret` When:

Use `set-var` When:

Example: Update ngrok URL

Example: Add a New API Key

Example: Switch to a Different Model

Viewing Secrets and Variables

Deleting Secrets and Variables