| name | ata-blog-cli |
| description | Use this skill for service operations only. DO NOT use this skill for CLI implementation lifecycle work such as creating, testing, updating, troubleshooting, validating, removing, or documenting the CLI tool itself; delegate those tasks to cli-tool-expert. MANDATORY: Execute ata-blog operations using the `ata-blog` CLI tool. CLI for managing ATA Blog (adamtheautomator.com) -- Notion pages, WordPress posts, WordPress pages, WordPress admin/plugin maintenance, media, categories, tags, Raptive ads, schema, earnings, shoutouts, and live ad-advertiser scanning. Triggers: ata-blog, ata blog, adamtheautomator, wordpress post, wordpress page, wordpress admin, plugin updates, update wordpress plugins, edit wordpress page, notion page publish, blog post, blog page, blog media, raptive ads, blog earnings, blog shoutouts, schema markup, scan ads, scan advertisers, what advertisers ran on this post, observed advertisers, include-ads, --include-ads, live ad scan |
Execute ata-blog operations using the `ata-blog` CLI. All ATA Blog interactions should use this CLI.
<quick_start>
The ata-blog CLI follows this pattern:
ata-blog <command-group> <action> [arguments] [options]
| Task | Command |
|---|
| List Notion pages | ata-blog notion-page list |
| Publish Notion page to WordPress | ata-blog notion-page publish <page_id> |
| List WordPress posts | ata-blog wordpress-post list |
| Get WordPress post fields | ata-blog wordpress-post get --properties id,title,slug,link,status,modified,content <post_id> |
| List WordPress pages | ata-blog wordpress-page list --table |
| Get page (raw HTML) | ata-blog wordpress-page get <page_id> --raw |
| Update page content | ata-blog wordpress-page update <page_id> --content-file page.html |
| List WordPress plugins | ata-blog wordpress-admin plugins list --properties "name,status,version" |
| Get WordPress plugin | ata-blog wordpress-admin plugins get <plugin> --properties "name,status,version" |
| Upgrade WordPress plugin | ata-blog wordpress-admin plugins upgrade <plugin> |
| List WordPress themes | ata-blog wordpress-admin themes list --table |
| Preview theme file push | ata-blog wordpress-admin themes file-push <theme> ./front-page.php front-page.php --remote-root /path/to/wp --host <ssh-host> --dry-run |
| Push theme file | ata-blog wordpress-admin themes file-push <theme> ./front-page.php front-page.php --remote-root /path/to/wp --host <ssh-host> --backup --yes |
| Upload media | ata-blog media upload <file_path> |
| Check ad earnings | ata-blog earnings get |
| Set schema on post | ata-blog schema set <post_id> <type> |
| Check Raptive ad status | ata-blog raptive status <post_id> |
| List shoutouts in a post | ata-blog shoutouts list <post_id> |
| List shoutouts by sponsor | ata-blog shoutouts list --sponsor Specops |
| Scan live advertisers on a post | ata-blog wordpress-post get --include-ads <post_id> |
| Scan advertisers on multiple posts | ata-blog wordpress-post list --include-ads --limit 5 |
| </quick_start> | |
<live_ad_scanning>
--include-ads on wordpress-post get (single post) or wordpress-post list (batch) live-scans the published URL using Playwright + playwright-stealth, extracts advertiser domains from Prebid's getAllWinningBids(), and merges them under a top-level ads key. Live-only -- no storage, no caching. Every invocation runs a fresh scan.
Syntax note: Flags must come BEFORE the post_id positional (typer allow_interspersed_args=False):
ata-blog wordpress-post get --include-ads --ad-checks 3 <post_id>
Key flags:
| Flag | Default | Meaning |
|---|
--include-ads / -A | off | enable the scan |
--ad-checks | 3 | reloads per scan |
--ad-interval | 5 | seconds between reloads |
--ad-timeout | 30 | max seconds per check |
Incompatible with --table (JSON only). Scan takes ~20-60s per post depending on --ad-checks.
Output shape under ads -- includes ALL bidders (winners AND losers) with full CPM stats. Each advertiser entry has won_count, appearances, bidders, min_cpm, avg_cpm, max_cpm. Losing bidders (won_count: 0) still reveal demand and CPM ranges.
ATA uses AdThrive/Raptive which strips googletag.getResponseInformation. The scanner installs a pre-page-load hook via context.add_init_script() that listens to Prebid's bidResponse, bidWon, noBid, and bidTimeout events -- capturing every bidder response, not just the final winners exposed by getAllWinningBids(). Works on Raptive-wrapped or GPT-wrapped sites.
</live_ad_scanning>
<essential_principles>
MANDATORY: Consult the adjacent usage.json at <cli-tools-root>/_repo/skills/<tool>-cli/usage.json before executing ANY ata-blog command.
This file contains complete command syntax, all arguments, all options, and usage instructions for every command. Never guess at command syntax.
`ata-blog auth status` can exit `2` while still emitting structured JSON that
reports the active profile with `"authenticated": false` and a message such as
`Not authenticated. Run 'ata-blog auth login' to configure.` When checking
whether auth exists, wrap the command and treat that unauthenticated JSON as an
expected diagnostic result only after validating both the `2` exit status and
`"authenticated": false`. Do not let the expected unauthenticated status surface
as an unhandled tool failure.
This service skill is not the lifecycle owner. For any ata-blog CLI source edit,
testing, or troubleshooting task, use the repo-owned `cli-tool` skill and its
`workflows/test-cli.md` procedure. The ata-blog source project lives at
`/_personal/ata-blog`; do not run ambient `python -m pytest` from
that directory. Focused source tests must use the uv project environment, for
example:
uv run --project /Users/adam/Dropbox/GitRepos/cli-tools/_personal/ata-blog --with pytest python -m pytest /Users/adam/Dropbox/GitRepos/cli-tools/_personal/ata-blog/tests/test_notion_statuses.py
`ata-blog wordpress-*` commands wrap the repo-owned `wordpress` CLI. For ATA
sitewide ACF option writes, do not use the ACF REST options endpoints when they
return `500 Cannot update item`; follow the `wordpress-cli` skill's ACF options
write guidance and use a server-side WordPress execution path instead.
If a diagnostic task must import WordPress CLI internals, there is no
wordpress_cli.auth module. Use the live wordpress launcher shebang
interpreter and the actual module documented by the wordpress-cli skill.
For sitewide ATA WordPress post cleanup, fetch raw post content with
`context=edit` and update through the WordPress CLI/API path. Do not rely on a
plain-text prefilter that expects disclosure copy to be contiguous text: live
content often wraps the label in tags such as `
Paid link disclosure:`.
Apply the narrow structural removal pattern to each post's raw HTML first, then
record a match only when the raw HTML actually changes. Verify completion with
an independent raw-content scan across all posts for the forbidden visible
snippets, not by reusing the same candidate-selection prefilter.
When running ATA WordPress plugin maintenance batches from Hermes, do not use a foreground `terminal` timeout above 600 seconds. For short commands, keep foreground `timeout` at `600` or lower. For long or multi-plugin batches, launch the command with `background=true` and `notify_on_complete=true`, then use `process` polling/waiting to collect the result. This prevents Hermes foreground timeout rejection while preserving real completion evidence.
- **auth** -- Authentication management (login, logout, status, refresh, test)
- **auth** -- Authentication commands and nested `auth profiles` management
- **notion-page** -- Notion page management (list, get, publish, update, search, statuses, comments, content)
- **wordpress-post** -- WordPress post CRUD (list, get, create, update, schedule, delete)
- **wordpress-page** -- WordPress page CRUD (list, get, create, update, delete). Passthrough to `wordpress pages`; pages support `parent`, `menu_order`, `template` (no tags/categories/format).
- **wordpress-admin** -- WordPress admin operations, including plugin list/get/activate/deactivate/delete/install/upgrade and theme list/get/file-push through the delegated `wordpress` CLI.
- **media** -- WordPress media management (list, get, upload, delete)
- **categories** -- WordPress categories (list, get, create)
- **tags** -- WordPress tags (list, get, create)
- **raptive** -- Raptive/AdThrive ad settings (disable, enable, status, fields)
- **schema** -- Rank Math schema markup (list, types, set, get, remove)
- **earnings** -- Ad earnings and revenue data (get, list)
- **shoutouts** -- Sponsored shoutouts in posts (list, get, add, remove)
<reference_index>
usage.json -- Complete command tree with arguments, options, defaults, and usage instructions for every command.
</reference_index>
<success_criteria>
- Command executes without error
- Output is displayed in requested format
- Correct command and flags used (verified against usage.json)
</success_criteria>
