### Run thepopebot Setup Wizard

Source: https://github.com/stephengpope/thepopebot/blob/main/README.md

Executes the setup wizard to configure environment variables, GitHub secrets, API keys, and Docker containers.

```bash
npm run setup
```

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

### Manual Telegram Setup (Production)

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/CONFIGURATION.md

Manual configuration steps for Telegram integration in production environments where the setup script cannot be run.

```APIDOC
## Manual Telegram Setup (Production)

If you're deploying to a platform where you can't run the setup script (Vercel, Railway, etc.), configure Telegram manually:

1. **Set environment variables** in your platform's dashboard (see `.env.example` for reference):
   - `TELEGRAM_BOT_TOKEN` - Your bot token from @BotFather
   - `TELEGRAM_WEBHOOK_SECRET` - Generate with `openssl rand -hex 32`
   - `TELEGRAM_VERIFICATION` - A verification code like `verify-abc12345`

2. **Deploy and register the webhook:**
   ```bash
   curl -X POST https://your-app.vercel.app/api/telegram/register \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_API_KEY" \
     -d '{"bot_token": "YOUR_BOT_TOKEN", "webhook_url": "https://your-app.vercel.app/api/telegram/webhook"}'
   ```
   This registers your webhook with the secret from your env.

3. **Get your chat ID:**
   - Message your bot with your `TELEGRAM_VERIFICATION` code (e.g., `verify-abc12345`)
   - The bot will reply with your chat ID

4. **Set `TELEGRAM_CHAT_ID`:**
   - Add the chat ID to your environment variables
   - Redeploy

Now your bot only responds to your authorized chat.
```

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

### Install Specific Thepopebot Pre-Release Version

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/PRE_RELEASE.md

This example shows how to install a specific pre-release version of thepopebot, such as a beta or release candidate. By replacing '@beta' with the exact version string (e.g., '@1.3.0-beta.1'), users can target precise pre-release builds. This command is used during the project initialization phase.

```bash
npx thepopebot@1.3.0-beta.1 init
```

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

### Start Production Services with Docker Compose

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/DEPLOYMENT.md

Launches the production environment using Docker Compose. This command starts services like Traefik (reverse proxy) and the event handler.

```bash
docker-compose up      # Start Traefik + event handler + runner
```

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

### Setup Telegram Integration

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/CHAT_INTEGRATIONS.md

Command to initialize the Telegram bot configuration wizard, which handles token setup, webhooks, and chat ID mapping.

```bash
npm run setup-telegram
```

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

### Initialize and Configure thepopebot on a Server

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/DEPLOYMENT.md

Steps to scaffold the thepopebot project, configure environment variables, and set up necessary secrets on a server. This includes running the initialization command and the setup script.

```bash
mkdir my-agent && cd my-agent
npx thepopebot@latest init
npm run setup
```

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

### Install YouTube Transcript Skill Dependencies

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/youtube-transcript/SKILL.md

Installs the necessary dependencies for the YouTube Transcript skill using npm. This command should be run from the skill's directory.

```bash
cd skills/youtube-transcript
npm install
```

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

### Install Node.js dependencies for brave-search skill

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Command to install Node.js dependencies for the brave-search skill. This is a prerequisite for using the skill.

```bash
npm install
```

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

### Install pi-skills for Claude Code

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Detailed instructions for integrating pi-skills with Claude Code. This involves cloning the repository and then creating symbolic links for individual skills into the Claude Code skills directory, supporting both user-level and project-level setups.

```bash
# Clone to a convenient location
git clone https://github.com/badlogic/pi-skills ~/pi-skills

# Symlink individual skills (user-level)
mkdir -p ~/.claude/skills
ln -s ~/pi-skills/brave-search ~/.claude/skills/brave-search
ln -s ~/pi-skills/browser-tools ~/.claude/skills/browser-tools
ln -s ~/pi-skills/gccli ~/.claude/skills/gccli
ln -s ~/pi-skills/gdcli ~/.claude/skills/gdcli
ln -s ~/pi-skills/gmcli ~/.claude/skills/gmcli
ln -s ~/pi-skills/transcribe ~/.claude/skills/transcribe
ln -s ~/pi-skills/vscode ~/.claude/skills/vscode
ln -s ~/pi-skills/youtube-transcript ~/.claude/skills/youtube-transcript

# Or project-level
mkdir -p .claude/skills
ln -s ~/pi-skills/brave-search .claude/skills/brave-search
ln -s ~/pi-skills/browser-tools .claude/skills/browser-tools
ln -s ~/pi-skills/gccli .claude/skills/gccli
ln -s ~/pi-skills/gdcli .claude/skills/gdcli
ln -s ~/pi-skills/gmcli .claude/skills/gmcli
ln -s ~/pi-skills/transcribe .claude/skills/transcribe
ln -s ~/pi-skills/vscode .claude/skills/vscode
ln -s ~/pi-skills/youtube-transcript .claude/skills/youtube-transcript
```

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

### Install Browser Tools Dependencies

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/browser-tools/SKILL.md

Installs the necessary Node.js dependencies for the browser-tools skill. This is a prerequisite before using any of the browser automation scripts.

```bash
cd skills/browser-tools
npm install
```

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

### Install Brave Search Dependencies

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/brave-search/SKILL.md

Initializes the project dependencies required for the Brave Search skill using npm.

```bash
cd skills/brave-search
npm install
```

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

### Install pi-skills for pi-coding-agent

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Instructions for cloning the pi-skills repository for use with the pi-coding-agent. Supports both user-level (global) and project-level installations.

```bash
# User-level (available in all projects)
git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills

# Or project-level
git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills
```

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

### Install gccli globally

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Command to install the Google Calendar CLI (gccli) globally using npm. This is a requirement for the gccli skill.

```bash
npm install -g @mariozechner/gccli
```

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

### Install pi-skills for Amp

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Instructions for installing pi-skills for Amp, which discovers skills recursively within toolboxes. The skill is cloned into the Amp configuration directory.

```bash
git clone https://github.com/badlogic/pi-skills ~/.config/amp/tools/pi-skills
```

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

### Install gmcli globally

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Command to install the Gmail CLI (gmcli) globally using npm. This is a requirement for the gmcli skill.

```bash
npm install -g @mariozechner/gmcli
```

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

### Run Local Development Server

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/DEPLOYMENT.md

Starts the Next.js development server for local testing and development. This command is typically used during the development phase.

```bash
npm run dev    # Next.js dev server
```

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

### Install pi-coding-agent globally

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Command to install the pi-coding-agent globally using npm. This is a requirement for the subagent skill.

```bash
npm install -g @mariozechner/pi-coding-agent
```

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

### Initialize Project with Thepopebot Beta Version

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/PRE_RELEASE.md

This snippet demonstrates how to create a new project and initialize it using the beta version of thepopebot. It involves creating a directory, changing into it, and then using npx to install and initialize the beta release. This is the primary method for opting into pre-release versions.

```bash
mkdir my-agent && cd my-agent
npx thepopebot@beta init
```

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

### Install gdcli globally

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Command to install the Google Drive CLI (gdcli) globally using npm. This is a requirement for the gdcli skill.

```bash
npm install -g @mariozechner/gdcli
```

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

### Implement a Simple Bash Skill

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/docs/SKILLS.md

An example of a bash script for a skill, including input validation and an API request using curl.

```bash
#!/bin/bash
if [ -z "$1" ]; then echo "Usage: my-skill.sh <arg>"; exit 1; fi
if [ -z "$MY_API_KEY" ]; then echo "Error: MY_API_KEY not set"; exit 1; fi
curl -s "https://api.example.com/endpoint" \
  -H "Authorization: Bearer $MY_API_KEY" \
  -d "query=$1"
```

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

### Install pi-skills for Droid (Factory)

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Commands for cloning pi-skills for the Droid (Factory) environment, supporting both user-level and project-level installations.

```bash
# User-level
git clone https://github.com/badlogic/pi-skills ~/.factory/skills/pi-skills

# Or project-level
git clone https://github.com/badlogic/pi-skills .factory/skills/pi-skills
```

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

### Configuring the Custom LLM Provider via CLI

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/docs/CONFIGURATION.md

This example demonstrates how to configure thepopebot to use a custom LLM provider, such as DeepSeek or Ollama, by pointing to an OpenAI-compatible API endpoint. It involves setting the `LLM_PROVIDER`, `LLM_MODEL`, `OPENAI_BASE_URL`, and the appropriate API key using the CLI.

```bash
# Cloud custom (DeepSeek, Together AI, etc.)
npx thepopebot set-var LLM_PROVIDER custom
npx thepopebot set-var LLM_MODEL deepseek-chat
npx thepopebot set-var OPENAI_BASE_URL https://api.deepseek.com/v1
npx thepopebot set-agent-secret CUSTOM_API_KEY sk-...
```

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

### Interact with thepopebot API via cURL

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/ARCHITECTURE.md

Demonstrates how to interact with thepopebot API endpoints using cURL. Includes examples for creating jobs, checking job status, and registering Telegram webhooks, all requiring an x-api-key header.

```bash
curl -X POST https://your-app-url/api/create-job \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"job": "Update the README with installation instructions"}'
```

```bash
curl "https://your-app-url/api/jobs/status?job_id=abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

```bash
curl -X POST https://your-app-url/api/telegram/register \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "bot_token": "YOUR_BOT_TOKEN",
    "webhook_url": "https://your-domain.com/api/telegram/webhook"
  }'
```

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

### Start Thepopebot Agent with Docker Compose

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/PRE_RELEASE.md

This command initiates the thepopebot agent using Docker Compose. It assumes that the project has been set up and configured, and the necessary Docker configurations are in place. The '-d' flag runs the containers in detached mode, allowing the terminal to be used for other tasks.

```bash
docker compose up -d
```

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

### POST /api/create-job

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/docs/GETTING_STARTED.md

Endpoint to trigger an autonomous coding job. The AI will create a branch, perform the requested task in a Docker container, and open a pull request.

```APIDOC
## POST /api/create-job

### Description
Triggers an autonomous coding task. The agent processes the request, performs the necessary code changes, and manages the PR lifecycle.

### Method
POST

### Endpoint
https://your-app-url/api/create-job

### Parameters
#### Request Body
- **job** (string) - Required - The description of the coding task for the agent to perform.

### Request Example
{
  "job": "Update the README with installation instructions"
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of job creation.
- **job_id** (string) - Unique identifier for the created job.

#### Response Example
{
  "status": "success",
  "job_id": "job_12345"
}
```

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

### Scaffold and Initialize thepopebot Project

Source: https://github.com/stephengpope/thepopebot/blob/main/README.md

Commands to create a new project directory and initialize thepopebot, which sets up the Next.js structure, GitHub workflows, and agent templates.

```bash
mkdir my-agent && cd my-agent
npx thepopebot@latest init
```

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

### GET /loadCrons

Source: https://context7.com/stephengpope/thepopebot/llms.txt

Loads scheduled jobs from CRONS.json and starts the cron scheduler.

```APIDOC
## GET /loadCrons

### Description
Loads scheduled jobs from CRONS.json and starts the cron scheduler. Supports agent, command, and webhook action types.

### Method
GET

### Endpoint
loadCrons()

### Response
#### Success Response (200)
- **tasks** (array) - List of loaded cron job objects.

#### Response Example
[
  { "name": "Daily Health Check", "schedule": "0 9 * * *", "type": "agent", "enabled": true }
]
```

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

### Initialize and Build thepopebot Project

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/DEPLOYMENT.md

Commands to scaffold, set up environment variables and secrets, and build the Next.js application for production. The build step generates the necessary output in the .next/ directory.

```bash
npx thepopebot init   # Scaffold project
npm run setup          # Configure .env, GitHub secrets, Telegram
npm run build          # Next.js build → generates .next/
```

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

### Execute CLI Commands for Project Management

Source: https://context7.com/stephengpope/thepopebot/llms.txt

Command-line interface tools for initializing projects, managing versions, updating environment variables, and handling database migrations.

```bash
npx thepopebot@latest init
npx thepopebot upgrade
npx thepopebot set-var APP_URL https://your-new-url.ngrok.io
npx thepopebot sync
npm run db:generate
npm run db:studio
```

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

### Install pi-skills for Codex CLI

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/skills/README.md

Command to clone the pi-skills repository for integration with Codex CLI, typically installed in a user-specific directory.

```bash
git clone https://github.com/badlogic/pi-skills ~/.codex/skills/pi-skills
```

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

### New Skill Creation: Directory Structure and Script (Bash)

Source: https://github.com/stephengpope/thepopebot/blob/main/templates/config/JOB_PLANNING.md

Defines the file structure and content for a new skill, specifically for posting to Slack. This includes creating markdown documentation, a bash script for the core functionality, and activating the skill.

```bash
# Create the skill directory
mkdir -p skills/slack-post

# Create SKILL.md
cat <<EOF > skills/slack-post/SKILL.md
---
name: slack-post
description: "Post messages to Slack channels via incoming webhook."
---

## Usage

```bash
skills/slack-post/post.sh <message>
```
EOF

# Create post.sh
cat <<EOF > skills/slack-post/post.sh
#!/bin/bash

MESSAGE="$1"
WEBHOOK_URL="$SLACK_WEBHOOK_URL"

if [ -z "$WEBHOOK_URL" ]; then
  echo "Error: SLACK_WEBHOOK_URL is not set."
  exit 1
fi

curl -X POST -H 'Content-type: application/json' --data "{\"text\":\"$MESSAGE\"}" "$WEBHOOK_URL"
EOF
chmod +x skills/slack-post/post.sh

# Activate the skill
ln -s ../slack-post skills/active/slack-post

# Test the skill
./skills/slack-post/post.sh "test message from thepopebot"
```

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

### Initialize Project with thepopebot CLI

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/CLI.md

Initializes a new project using the thepopebot CLI, scaffolding necessary files and directories. It automatically updates managed files while leaving user files untouched. Use `--no-managed` to prevent overwriting custom changes in managed files.

```bash
npx thepopebot init
npx thepopebot init --no-managed
```

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

### Build and Launch Application

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/DEPLOYMENT.md

Commands to compile the application using npm and deploy the containerized services in detached mode using Docker Compose.

```bash
npm run build
docker compose up -d
```

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

### GET /api/jobs/status

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/ARCHITECTURE.md

Retrieves the status of a running job.

```APIDOC
## GET /api/jobs/status

### Description
Check the status of a specific job using its ID.

### Method
GET

### Endpoint
/api/jobs/status

### Parameters
#### Query Parameters
- **job_id** (string) - Required - The unique identifier for the job.

### Request Example
curl "https://your-app-url/api/jobs/status?job_id=abc123" -H "x-api-key: YOUR_API_KEY"
```

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

### Example: Different Models for Chat and Jobs

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/RUNNING_DIFFERENT_MODELS.md

Demonstrates configuring the Event Handler to use Anthropic's Claude for chat and Jobs to use a local Ollama model via the 'custom' provider. This involves setting `.env` variables for the Event Handler and GitHub repo variables for Jobs.

```bash
# Event Handler (.env):
LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-4-20250514
ANTHROPIC_API_KEY=sk-ant-...
```

```bash
# Jobs (GitHub repo variables):
npx thepopebot set-var LLM_PROVIDER custom
npx thepopebot set-var LLM_MODEL qwen3:8b
npx thepopebot set-var OPENAI_BASE_URL http://host.docker.internal:11434/v1
npx thepopebot set-var RUNS_ON self-hosted
```

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

### runCodeWorkspaceContainer

Source: https://context7.com/stephengpope/thepopebot/llms.txt

Creates and starts an interactive code workspace Docker container with terminal access.

```APIDOC
## runCodeWorkspaceContainer

### Description
Creates and starts an interactive code workspace Docker container with terminal access.

### Method
Not applicable (JavaScript function)

### Endpoint
Not applicable (JavaScript function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (object) - Required - Configuration options for the container.
  - **containerName** (string) - Required - The name for the Docker container.
  - **repo** (string) - Required - The repository to clone (e.g., 'owner/my-repo').
  - **branch** (string) - Required - The branch to checkout.
  - **codingAgent** (string) - Required - The coding agent to use (e.g., 'claude-code', 'pi-coding-agent', 'gemini-cli').
  - **featureBranch** (string) - Optional - The feature branch to use.
  - **workspaceId** (string) - Optional - The ID of the workspace.
  - **chatContext** (string) - Optional - JSON stringified chat context.

### Request Example
```javascript
await runCodeWorkspaceContainer({
  containerName: 'claude-code-interactive-abc12345',
  repo: 'owner/my-repo',
  branch: 'main',
  codingAgent: 'claude-code',
  featureBranch: 'thepopebot/feature-abc12345',
  workspaceId: 'ws-abc-123',
  chatContext: JSON.stringify({
    title: 'Add Authentication',
    messages: [
      { role: 'user', content: 'Add JWT authentication to the API' }
    ]
  })
});
```

### Response
#### Success Response (200)
- **containerId** (string) - The ID of the created container.
- **containerName** (string) - The name of the created container.
- **backendApi** (string) - The backend API used.

#### Response Example
```json
{
  "containerId": "abc123...",
  "containerName": "claude-code-interactive-abc12345",
  "backendApi": "anthropic"
}
```
```

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

### POST /createJob

Source: https://context7.com/stephengpope/thepopebot/llms.txt

Creates a new job branch with configuration for the Docker agent to execute.

```APIDOC
## POST /createJob

### Description
Creates a new job branch with configuration for the Docker agent to execute. Returns job ID, branch name, and auto-generated title.

### Method
POST

### Endpoint
createJob(jobDescription, options)

### Parameters
#### Request Body
- **jobDescription** (string) - Required - Description of the task to perform.
- **options** (object) - Optional - LLM overrides including llmProvider, llmModel, and agentBackend.

### Request Example
{
  "jobDescription": "Add unit tests for the authentication module",
  "options": { "llmProvider": "openai", "llmModel": "gpt-4o" }
}

### Response
#### Success Response (200)
- **job_id** (string) - Unique ID of the created job.
- **branch** (string) - Git branch associated with the job.
- **title** (string) - Auto-generated title for the job.

#### Response Example
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "branch": "job/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Add unit tests for authentication module"
}
```

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

### GET /api/ping

Source: https://github.com/stephengpope/thepopebot/blob/main/api/CLAUDE.md

This endpoint serves as a health check for the API. It requires no authentication and is used to verify if the API is operational.

```APIDOC
## GET /api/ping

### Description
Performs a health check to verify if the API is operational.

### Method
GET

### Endpoint
/api/ping

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status of the API (e.g., "ok").

#### Response Example
{
  "status": "ok"
}
```

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

### GET /api/jobs/status

Source: https://github.com/stephengpope/thepopebot/blob/main/api/CLAUDE.md

Retrieves the status of a specific job. This endpoint requires an API key and accepts a `job_id` query parameter.

```APIDOC
## GET /api/jobs/status

### Description
Retrieves the status of a specific job. Requires authentication via `x-api-key` header.

### Method
GET

### Endpoint
/api/jobs/status

### Parameters
#### Path Parameters
None

#### Query Parameters
- **job_id** (string) - Required - The ID of the job whose status is to be retrieved.

#### Request Body
None

### Request Example
```
GET /api/jobs/status?job_id=job-abc789
```

### Response
#### Success Response (200)
- **job_id** (string) - The ID of the job.
- **status** (string) - The current status of the job (e.g., "completed", "failed", "in_progress").
- **result** (any) - Optional - The result of the job if completed.

#### Response Example
```json
{
  "job_id": "job-abc789",
  "status": "completed",
  "result": {
    "processed_records": 1000
  }
}
```
```

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

### Updating APP_URL

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/CONFIGURATION.md

Steps to update the public URL for thepopebot if it changes, for example, after restarting ngrok or changing domains.

```APIDOC
## APP_URL Changes

If your public URL changes (e.g., after restarting ngrok or changing domains):

1. Update `APP_URL` and `APP_HOSTNAME` in your `.env` file
2. Update the `APP_URL` GitHub repository variable
3. Restart Docker: `docker compose up -d`
4. If Telegram is configured, re-register the webhook:

```bash
npm run setup-telegram
```
```

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

### Configure Cloud Custom Provider via CLI

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/RUNNING_DIFFERENT_MODELS.md

Sets up the 'custom' LLM provider for cloud services like DeepSeek, Together AI, or Fireworks by specifying the provider, model, and the OpenAI-compatible base URL. The API key is then set as a GitHub secret.

```bash
npx thepopebot set-var LLM_PROVIDER custom
npx thepopebot set-var LLM_MODEL deepseek-chat
npx thepopebot set-var OPENAI_BASE_URL https://api.deepseek.com/v1
```

```bash
npx thepopebot set-agent-secret CUSTOM_API_KEY sk-...
```

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

### Activate a Skill in thepopebot

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/CUSTOMIZATION.md

This bash command demonstrates how to activate a skill by creating a symbolic link from the 'skills/active' directory to the desired skill's directory. This is a common pattern for enabling specific functionalities within the project.

```bash
cd skills/active
ln -s ../skill-name skill-name
```

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

### Health Check - GET /api/ping

Source: https://context7.com/stephengpope/thepopebot/llms.txt

A simple health check endpoint to verify if the ThePopeBot event handler is operational. This endpoint does not require any authentication.

```APIDOC
## GET /api/ping

### Description
Simple health check endpoint that confirms the event handler is running.

### Method
GET

### Endpoint
/api/ping

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **message** (string) - Indicates the status of the service.

#### Response Example
```json
{"message": "Pong!"}
```
```

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

### Docker Compose Deployment

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/CONFIGURATION.md

Instructions for deploying thepopebot using Docker Compose for self-hosted environments.

```APIDOC
## Docker Compose Deployment

For self-hosted deployment, build the project and start Docker:

```bash
npm run build
docker compose up -d
```

**Important:** The `.next/` build directory must exist before starting the container. If the container starts without a valid build, it will crash-loop until one is available.

This starts three services:
- **Traefik** — Reverse proxy with automatic SSL (Let's Encrypt if `LETSENCRYPT_EMAIL` is set)
- **Event Handler** — Node.js runtime + PM2, serves the bind-mounted Next.js app on port 80. An anonymous volume (`/app/node_modules`) preserves the container's pre-built Linux-compiled native modules (like `better-sqlite3`)
- **Runner** — Self-hosted GitHub Actions runner for executing jobs

Set `RUNS_ON=self-hosted` as a GitHub repository variable to route workflows to your runner.

See the [Architecture docs](ARCHITECTURE.md) for more details.
```

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

### Generate Claude OAuth Token

Source: https://github.com/stephengpope/thepopebot/blob/main/README.md

Installs the Claude Code CLI and generates an OAuth token to use a Claude Pro subscription for agent jobs instead of standard API calls.

```bash
npm install -g @anthropic-ai/claude-code
claude setup-token
```

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

### Register Telegram Webhook

Source: https://github.com/stephengpope/thepopebot/blob/main/docs/CONFIGURATION.md

Command to manually register the Telegram webhook for production environments where setup scripts cannot be run. Requires API key and bot details.

```bash
curl -X POST https://your-app.vercel.app/api/telegram/register \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"bot_token": "YOUR_BOT_TOKEN", "webhook_url": "https://your-app.vercel.app/api/telegram/webhook"}'
```