Skip to main content

Examples & tips

The CLI is useful when you want Woodpecker data close to where you already work: in a terminal, a script, or an AI coding agent. You can check campaign state, add entries to a blacklist, generate reports, fetch replies, or ask an agent to inspect account data and summarize what needs attention.

If you work with agency accounts, you can also scope account-level commands to a client company with --company-id.

These examples are meant to show practical patterns. For the full command list, flags and output details, see the npm package README.

tip

Use --json or --output json for deterministic output in scripts and AI-agent workflows. Human output is better for manual terminal checks, but JSON output is easier to parse.

Manual terminal checks​

Use the CLI when you need a quick answer and do not want to navigate through the UI.

List running and paused campaigns:

woodpecker campaigns list --status RUNNING,PAUSED

Check campaign details by ID:

woodpecker campaigns get 1406957

Add an email address to the account blacklist:

woodpecker blacklist emails add --emails blacklisted@mail.com

Run an account-level command for a specific client company:

woodpecker --company-id 123 campaigns list --status RUNNING

Recurring scripts​

This example generates a campaigns report for the previous 30 days, waits for it to be ready and saves the result to a local JSON file:

#!/usr/bin/env bash
set -euo pipefail

: "${WOODPECKER_API_KEY:?Set WOODPECKER_API_KEY first}"

report_hash="$(
  woodpecker --json reports generate campaigns --last-30-days |
  jq -r '.hash'
)"

woodpecker --json reports poll "$report_hash" --attempts 10 --interval-ms 2000 > campaign-report.json
jq -r '.status' campaign-report.json

Save it as campaign-report.sh, then run it manually first:

export WOODPECKER_API_KEY="{YOUR_API_KEY}"
chmod +x campaign-report.sh
./campaign-report.sh

If the script prints READY and creates campaign-report.json, it works. After that, run it from your scheduler of choice, such as cron, GitHub Actions or another CI job. For scheduled jobs, load WOODPECKER_API_KEY from your platform secret manager instead of storing the key in the script.

AI-agent workflows​

CLI commands are useful when an AI coding agent can run shell commands in your workspace. The agent can ask Woodpecker for current data, parse JSON, and then help you decide what to do next.

Example prompts:

Use the Woodpecker CLI to fetch my latest inbox replies. Summarize who replied, and point out replies that I should prioritize first.
Use the Woodpecker CLI to generate a campaigns report for the last 30 days, wait until the report is ready, and summarize the main campaign performance patterns.