kisstour-ads — Command Cheatsheet

Quick reference cho 9 commands CLI. Tất cả read-only (không mutate Google Ads account).

Prefix mọi lệnh: npm run ads -- <command> [flags]

Quick reference

Common workflows

Weekly optimization review (mỗi thứ Hai)

npm run ads -- campaign-metrics --days 7
npm run ads -- suggest-negatives --days 7
npm run ads -- suggest-pauses --days 7
# Mở .suggestions/*.html cho colleague review + share với owner

Monthly report cho owner

npm run ads -- campaign-metrics --days 30
npm run ads -- search-terms --days 30 --zero-conv --limit 50
npm run ads -- suggest-negatives --days 30
# HTML file ở .suggestions/ send cho owner

New keyword research

npm run ads -- keyword-ideas "<seed phrase>" --geo VN --lang EN --limit 30 --min-volume 500

Pre-Phase-1 (khi colleague chuẩn bị rewrite ad copy)

npm run ads -- ad-copy-audit
# .audits/*.md liệt kê 16 OLD ads cần rewrite kèm headlines hiện tại

Snapshot trước khi thay đổi lớn

npm run ads -- snapshot
# Commit .snapshots/<stamp>.json vào git để rollback-compare sau

Detail per command

list-campaigns

Liệt kê toàn bộ campaigns với status, channel, budget, dates.

npm run ads -- list-campaigns

Flags: none

Output: Console table cột id, name, status, channel, budget_VND, start, end.

snapshot

Dump cấu trúc ENABLED campaigns ra file markdown + JSON. Dùng để diff qua thời gian.

npm run ads -- snapshot

Flags: none (dùng SNAPSHOT_DIR env var để đổi output dir, default .snapshots/)

Output:

• .snapshots/<YYYY-MM-DD_HH-MM>.md — human readable
• .snapshots/<YYYY-MM-DD_HH-MM>.json — diff-able

Chứa: campaigns + ad groups + ads (RSA headlines/descriptions) + keywords (positive + negative).

campaign-metrics

Aggregate metrics per campaign trong period. Tools để overview account health.

npm run ads -- campaign-metrics --days 30

Flags:

• --days N — số ngày lookback (default 30)

Output table cols: id, name, status, impr, clicks, ctr_pct, avg_cpc_VND, cost_VND, conv, cost_per_conv_VND

Note: Excludes REMOVED campaigns. Hiển thị cả PAUSED để biết campaigns nào đang off.

keyword-performance

Top keywords theo cost với metrics + quality score.

npm run ads -- keyword-performance --days 30
npm run ads -- keyword-performance --campaign 23772226224 --days 7 --limit 20

Flags:

• --campaign ID — filter theo campaign (default all)
• --days N — default 30
• --limit N — default 50

Output cols: keyword, match, campaign, ad_group, qs, impr, clicks, ctr_pct, avg_cpc_VND, cost_VND, conv

Sorted by cost desc. Excludes negative keywords. Excludes status=REMOVED.

search-terms

Các query user thực sự gõ lên Google triggering ads của mình. Gold mine cho negatives + positive opportunities.

npm run ads -- search-terms --days 30 --limit 50
npm run ads -- search-terms --days 7 --zero-conv
npm run ads -- search-terms --campaign 21054320529 --days 30

Flags:

• --campaign ID — filter
• --days N — default 30
• --limit N — default 100
• --zero-conv — chỉ hiện search terms với 0 conversions (useful for negative hunting)

Output cols: search_term, status, triggered_by, match, campaign, impr, clicks, ctr_pct, cost_VND, conv

Status values:

• NONE — chưa add làm positive hay negative
• ADDED — đã là positive keyword trong cùng ad group
• EXCLUDED — đã là negative keyword
• ADDED_EXCLUDED — cả 2 (setup lộn xộn)

keyword-ideas

Google Keyword Planner suggestions cho 1 seed phrase. Research volume + CPC estimate + competition.

npm run ads -- keyword-ideas "ho chi minh food tour"
npm run ads -- keyword-ideas "saigon motorbike" --geo HCMC --lang EN --limit 30
npm run ads -- keyword-ideas "vietnam tour" --geo VN,US --min-volume 1000

Flags:

• <seed> (positional, bắt buộc, có thể nhiều seeds)
• --geo X — alias hoặc raw ID (default VN). Aliases: VN (2704), HCMC (1028581), HANOI (1028580), US (2840)
• --lang X — alias hoặc raw ID (default EN). Aliases: EN (1000), VI (1014)
• --limit N — top N theo volume (default 50)
• --min-volume N — filter keywords với avg monthly < N (default 0)

Output cols: keyword, avg_monthly, competition (LOW/MEDIUM/HIGH), comp_idx, low_cpc_VND, high_cpc_VND

Multi-geo: --geo VN,US,HCMC — combine data từ nhiều locations.

suggest-negatives

Phân tích search terms, propose negative keywords. Output có HTML cho owner + MD cho checkbox approval.

npm run ads -- suggest-negatives --days 30
npm run ads -- suggest-negatives --days 7 --min-cost 30000 --min-clicks 2
npm run ads -- suggest-negatives --campaign 23772226224 --days 14

Flags:

• --campaign ID — filter
• --days N — default 30
• --min-cost N — ngưỡng cost VND (default 50000)
• --min-clicks N — ngưỡng clicks (default 3)
• --dir PATH — output dir (default .suggestions)
• --format md|html|both — default both. Dùng md nếu pipeline script không cần HTML, html nếu chỉ gửi owner

Output (2 files by default):

• .suggestions/<YYYY-MM-DD>-negatives.md — MD với checkbox [ ] cho dev/colleague approval
• .suggestions/<YYYY-MM-DD>-negatives.html — HTML rich report cho company owner (4 verdict sections: Approve / Add positive / Competitor / Review)

Workflow: Colleague mở .md, tick [x] items approve → (Phase 3, chưa build) chạy apply-negatives để push qua API.

Logic filter: chỉ search terms với status=NONE (chưa add làm positive/negative ở ad group đó).

suggest-pauses

Propose keywords nên pause (CTR thấp + cost cao).

npm run ads -- suggest-pauses --days 30
npm run ads -- suggest-pauses --days 30 --min-clicks 50 --max-ctr 2 --min-cost 200000

Flags:

• --campaign ID
• --days N — default 30
• --min-clicks N — default 30 (cần đủ data để kết luận)
• --max-ctr N — CTR threshold % (default 3)
• --min-cost N — cost threshold VND (default 100000)
• --dir PATH — default .suggestions

Output: .suggestions/<date>-pauses.md

Signal: high cost + low CTR = ad copy không resonate với query intent. Cân nhắc pause hoặc rewrite ad copy.

ad-copy-audit

Quét ENABLED RSAs, classify mỗi ad như NEW pattern (KissTour + Since 2017 style) vs OLD pattern (DKI + legacy phrases) vs non-RSA.

npm run ads -- ad-copy-audit
npm run ads -- ad-copy-audit --campaign 21054320529

Flags:

• --campaign ID — filter
• --dir PATH — default .audits

Output: .audits/<YYYY-MM-DD>-ad-copy-audit.md

Per ad: classification badge + full dump của headlines/descriptions hiện tại. Input cho Phase 1 (update-rsa) khi colleague rewrite copy.

Classification logic:

• OLD: có DKI {Keyword:...} OR legacy phrase (#GirlPower, Ranked #1 TripAdvisor, Licensed And Safe)
• NEW: có "KissTour"/"Kiss Tour" + "Since 2017"/"Original Since"
• UNKNOWN: không match pattern nào rõ
• non-RSA: ad type khác (Demand Gen, Performance Max...)

Environment

• Node >= 22 (dùng built-in --env-file, không cần dotenv)
• .env phải có 6 vars: GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_OAUTH_CLIENT_ID, GOOGLE_ADS_OAUTH_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_LOGIN_CUSTOMER_ID, GOOGLE_ADS_CUSTOMER_ID
• Values copy từ kisstour-base/.local/google-ads/.env

Output directories (all gitignored)

• .snapshots/ — full dumps (md + json)
• .suggestions/ — proposed changes (md + html)
• .audits/ — classification reports (md)

Related docs

• suggest-negatives guide — cách đọc output file, framework approve/reject, match type strategy
• Google Ads baseline 2026-04-23 — snapshot sau colleague restructure
• Roadmap — Phase 0-5 plan